For AI agents: markdown of this page — /docs-content-en/applications/app-secrets/create.md documentation index — /llms.txt

Create a secret name

POST /v1/applications/:id/secrets

Creates a secret name without a value: the owner or the Bitrix24 account administrator then sets the value on the application card. The call applies nothing and does not restart the application.

Parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionApplication card ID. This is not the ID of an OAuth application or a server. List: GET /v1/applications

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionSecret name, up to 128 characters, ^[A-Za-z_][A-Za-z0-9_]*$. PORT and the prefixes VIBE_ and HERMES_EVENT_INGEST_ are not allowed. An application has at most 100 author names; system secrets do not count toward this limit

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/applications/cmsw806qi0000tdskiw2aegii/secrets \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "PAYMENT_TOKEN"}'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/applications/cmsw806qi0000tdskiw2aegii/secrets \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "PAYMENT_TOKEN"}'

JavaScript — personal key

javascript 
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.com/v1/applications/${id}/secrets`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'PAYMENT_TOKEN' }),
})
const { data } = await res.json()

console.log(data.secret.name, data.secret.hasValue)

JavaScript — OAuth application

javascript 
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.com/v1/applications/${id}/secrets`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'PAYMENT_TOKEN' }),
})
const { data } = await res.json()

Response fields

Success — HTTP 201.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.secret.name Typestring DescriptionSecret name
Fielddata.secret.kind Typestring DescriptionAlways user: this method creates only secrets of the application author
Fielddata.secret.hasValue Typeboolean DescriptionAlways false: the value is set on the application card
Fielddata.secret.createdAt Typestring DescriptionWhen the name was created, ISO 8601
Fielddata.secret.createdBy Typestring DescriptionID of the user who created the name
Fielddata.secret.updatedAt Typestring DescriptionTime of the last change, ISO 8601
Fielddata.secret.updatedBy Typestring DescriptionID of the author of the last change
Fielddata.secret.updatedByName Typestring DescriptionName of the author of the last change
Fielddata.state Typeobject DescriptionState of applying the set
Fielddata.state.desiredRevision Typenumber DescriptionNumber of the current set. Creating a name does not change it
Fielddata.state.appliedRevision Typenumber DescriptionNumber of the set the application has confirmed receiving
Fielddata.state.appliedServerId Typestring | null DescriptionID of the server where the set is applied. Matches server.id in GET /v1/applications/:id
Fielddata.state.status Typestring DescriptionPENDING, APPLYING, APPLIED or FAILED. The values are described under state.status on the List application secrets page
Fielddata.state.failureCode Typestring | null DescriptionFailure reason when FAILED. The codes are in the "Failure and retry" section of Application secrets
Fielddata.state.deliveredNames Typearray DescriptionNames the platform has already passed to the application, including deleted ones
Fielddata.state.serviceName Typestring | null DescriptionThe application's service on a standalone machine, recorded by the platform on deploy. null in Galaxy and before such a deploy
Fielddata.state.updatedAt Typestring DescriptionTime of the last state change, ISO 8601

Response example

JSON 
{
  "success": true,
  "data": {
    "secret": {
      "name": "PAYMENT_TOKEN",
      "kind": "user",
      "hasValue": false,
      "createdAt": "2026-10-22T12:45:13.146Z",
      "updatedAt": "2026-10-22T12:45:13.187Z",
      "createdBy": "3f6c1a52-8b1e-4c7a-9d2f-5e0b7a4c1d93",
      "updatedBy": "3f6c1a52-8b1e-4c7a-9d2f-5e0b7a4c1d93",
      "updatedByName": "Anna Smith"
    },
    "state": {
      "desiredRevision": 0,
      "appliedRevision": 0,
      "appliedServerId": null,
      "status": "PENDING",
      "failureCode": null,
      "deliveredNames": [],
      "serviceName": null,
      "updatedAt": "2026-10-22T12:45:13.206Z"
    }
  }
}

Error response example

400 — the body contains a value:

JSON 
{
  "success": false,
  "error": {
    "code": "SECRET_VALUE_NOT_ACCEPTED",
    "message": "Set secret values in the application card.",
    "applicationUrl": "/applications?app=cmsw806qi0000tdskiw2aegii"
  }
}

error.applicationUrl points to the application card, where the owner sets the value.

Errors

HTTP Code Description
HTTP400 CodeSECRET_VALUE_NOT_ACCEPTED DescriptionThe body has a value field, even an empty one. Set the value on the application card
HTTP400 CodeSECRET_INVALID_NAME DescriptionInvalid or reserved name, other than a system secret name
HTTP400 CodeSECRET_INVALID_REQUEST DescriptionInvalid request body: not JSON, no name, name is not a string, or there are extra fields
HTTP400 CodeSECRET_LIMIT_REACHED DescriptionThe application already has 100 author names. System secrets are not counted
HTTP404 CodeAPPLICATION_NOT_FOUND DescriptionThe application does not exist or there is no access to it, including an application on a different machine than the one the development member's key is linked to. Or the feature is not enabled for the portal
HTTP409 CodeSECRET_ALREADY_EXISTS DescriptionThe name already exists. Its value and data stay unchanged
HTTP409 CodeSECRET_SYSTEM DescriptionA platform system secret name — VIBE_AUTH_SECRET, VIBE_AUTH_SECRET_PREVIOUS or VIBE_AUTH_SECRET_REVOKED. Only the platform creates these secrets. The answer is the same even if the application has no such secret
HTTP413 CodeSECRET_BODY_TOO_LARGE DescriptionThe request body exceeds 128 KiB
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionKey not found
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionA read-only key cannot create names
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionA Cowork subscription key with the vibe:cowork scope cannot create names
HTTP403 CodeEXTERNAL_COLLABORATOR_KEY_SERVER_MISMATCH DescriptionThe external development member's key is not linked to a machine, and the application has no machine either
HTTP403 CodeEXTERNAL_COLLABORATOR_NOT_A_MEMBER DescriptionKey of an external development member whose membership on the machine was revoked or has expired
HTTP403 CodePORTAL_COLLABORATOR_NOT_A_MEMBER DescriptionKey of a development team member who is no longer in the machine's team or is not linked to it
HTTP429 CodeRATE_LIMIT_EXCEEDED DescriptionThe secrets methods limit is 60 requests per minute per user within a portal, shared by the list, create and delete methods and split across replicas. A rejection by the general API request limit comes with the same code. x-ratelimit-limit reports the effective limit for the key
HTTP500 CodeSECRET_OPERATION_FAILED DescriptionThe operation failed. The response does not include the original error

Full list of common API errors — Errors.

See also