Create a secret

Store a value as a secret, encrypted under one of your KMS keys, as the Default or for one environment.

Last updated 18 November 2026View as Markdown

Replace STRIPE_API_KEY with the name apps and workflows will look the value up by, and 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d with the id of an enabled KMS key.

Prerequisites

  • Permission for secrets:CreateSecret. In the console, also secrets:ListSecrets to open Secrets; without it the page says "You do not have permission to list secrets."
  • An enabled encrypt_decrypt KMS key. Without one, the console's Create secret offers Create an encryption key (kms:CreateKey) and brings you back to the form.
  • To create it in an environment, the environment's id (see Manage environments). In the console, the Environment picker lists the environments only with secrets:ListSecretEnvironments; without it, it offers Default only.
  • A free unit of the secrets quota; see Quotas.

Create the secret

  1. Open Secrets, then choose Create secret.
  2. For Name, enter STRIPE_API_KEY.
  3. For Value, paste the value.
  4. (Optional) For Group, choose or enter a group such as payments.
  5. For Environment, keep Default for every environment, or choose one environment to override the Default there.
  6. (Optional) For Description, enter what the value is for.
  7. (Optional) Under Key and rotation, choose another Encryption key, or enter a number of days (1 to 3650) for Remind me to rotate every (days). For Scope, choosing Project or Resource adds a required field of that name: enter the project or the resource name it is filed under.
  8. (Optional) Under Tags, add tags. A tag your organization requires must be set before the form can be sent.
  9. Choose Create secret.

The secret appears in the list as v1.

To create a secret whose value comes from 1Password or Vault, see Sync a secret from a source.

Result

The answer is 201 with the secret, never its value. The value is version 1. No consumer may read it yet; see Grant a consumer access to a secret.

A name that already exists in another environment keeps that name's group, whatever group you send.

Refusals

  • 409 "A shared secret named STRIPE_API_KEY already exists", or "STRIPE_API_KEY already exists in that environment".
  • 404 "Environment not found"; 404 "Key not found".
  • 409 "Key is not enabled"; 400 "Key must be an encrypt_decrypt key".
  • 400 "Give either a value or a reference, not both", when both or neither are sent.
  • 409 when the secrets quota is full.
Did this page help you?