Create a secret

Create an encrypted Runpod account secret that Pods, Serverless endpoints, and templates can reference from environment variables at boot.

POST /v2/account/secrets

Create a secret

cURL

curl --request POST \
  --url https://api.runpod.io/v2/account/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "hf-token",
  "value": "hf_********************************",
  "description": "Hugging Face read token"
}
'

201

{
  "id": "2q9m7x4cavgd",
  "name": "hf-token",
  "description": "Hugging Face read token",
  "createdAt": "2026-09-10T17:23:45Z",
  "valueLastUpdatedAt": "2026-09-10T17:23:45Z"
}

Authorizations

Authorization · string · header · required

Runpod API key authentication. Generate an API key in the Runpod console and send it in the Authorization header as Bearer <api_key>. Keys are scoped to the permissions granted when created; requests may return 403 when a valid key lacks access to the requested resource or action.

Body

application/json

name · string · required

Unique name for the secret — referenced from environment variables as {{ RUNPOD_SECRET_<name> }}; immutable after creation. Maximum 191 characters, must start with a letter or underscore, and may contain letters, digits, and _.-/. Names beginning with the reserved prefix RUNPOD are rejected (case-insensitive).

Required string length: 1 - 191

Pattern: ^[a-zA-Z_][a-zA-Z0-9_.\-/]*$

Example:

"hf-token"

value · string · required

The secret value. Write-only — never returned by the API. Must be smaller than 16 MiB of UTF-8 text (strictly under 16,777,216 bytes).

Required string length: 1 - 16777216

description · string

Optional human-readable description, at most 65,535 bytes of UTF-8 text.

Maximum string length: 65535

Example:

"Hugging Face read token"

Response

201

application/json

Created

An account-scoped secret: an encrypted string stored by Runpod, referenced from pod, serverless, and template environment variables with the {{ RUNPOD_SECRET_<name> }} placeholder, substituted with the secret's value when the pod or worker boots. The value is write-only and never returned by the API.

id · string · required

Unique secret identifier

Example:

"2q9m7x4cavgd"

name · string · required

Unique, human-readable name — the <name> referenced by the RUNPOD_SECRET_<name> placeholder. Immutable after creation.

Example:

"hf-token"

createdAt · string<date-time> · required

When the secret was created

description · string | null

Human-readable description

Example:

"Hugging Face read token"

valueLastUpdatedAt · string<date-time> | null

When the secret's value was last set (creation or rotation)