[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-applications\u002Fapp-secrets\u002Fcreate":3,"docs-tabs-applications\u002Fapp-secrets\u002Fcreate":6},{"content":4,"lastmod":5},"## Create a secret name\n\n`POST \u002Fv1\u002Fapplications\u002F:id\u002Fsecrets`\n\nCreates 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.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `id` (path) | string | yes | Application card ID. This is not the ID of an OAuth application or a server. List: [`GET \u002Fv1\u002Fapplications`](\u002Fdocs\u002Fapplications\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `name` | string | yes | Secret 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 |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fapplications\u002Fcmsw806qi0000tdskiw2aegii\u002Fsecrets \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"name\": \"PAYMENT_TOKEN\"}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fapplications\u002Fcmsw806qi0000tdskiw2aegii\u002Fsecrets \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"name\": \"PAYMENT_TOKEN\"}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst id = 'cmsw806qi0000tdskiw2aegii'\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fapplications\u002F${id}\u002Fsecrets`, {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ name: 'PAYMENT_TOKEN' }),\n})\nconst { data } = await res.json()\n\nconsole.log(data.secret.name, data.secret.hasValue)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst id = 'cmsw806qi0000tdskiw2aegii'\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fapplications\u002F${id}\u002Fsecrets`, {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ name: 'PAYMENT_TOKEN' }),\n})\nconst { data } = await res.json()\n```\n\n## Response fields\n\nSuccess — HTTP `201`.\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` on success |\n| `data.secret.name` | string | Secret name |\n| `data.secret.kind` | string | Always `user`: this method creates only secrets of the application author |\n| `data.secret.hasValue` | boolean | Always `false`: the value is set on the application card |\n| `data.secret.createdAt` | string | When the name was created, ISO 8601 |\n| `data.secret.createdBy` | string | ID of the user who created the name |\n| `data.secret.updatedAt` | string | Time of the last change, ISO 8601 |\n| `data.secret.updatedBy` | string | ID of the author of the last change |\n| `data.secret.updatedByName` | string | Name of the author of the last change |\n| `data.state` | object | State of applying the set |\n| `data.state.desiredRevision` | number | Number of the current set. Creating a name does not change it |\n| `data.state.appliedRevision` | number | Number of the set the application has confirmed receiving |\n| `data.state.appliedServerId` | string \\| null | ID of the server where the set is applied. Matches `server.id` in [`GET \u002Fv1\u002Fapplications\u002F:id`](\u002Fdocs\u002Fapplications\u002Fget) |\n| `data.state.status` | string | `PENDING`, `APPLYING`, `APPLIED` or `FAILED`. The values are described under `state.status` on the [List application secrets](\u002Fdocs\u002Fapplications\u002Fapp-secrets\u002Flist) page |\n| `data.state.failureCode` | string \\| null | Failure reason when `FAILED`. The codes are in the \"Failure and retry\" section of [Application secrets](\u002Fdocs\u002Fapplications\u002Fapp-secrets) |\n| `data.state.deliveredNames` | array | Names the platform has already passed to the application, including deleted ones |\n| `data.state.serviceName` | string \\| null | The application's service on a standalone machine, recorded by the platform on deploy. `null` in Galaxy and before such a deploy |\n| `data.state.updatedAt` | string | Time of the last state change, ISO 8601 |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"secret\": {\n      \"name\": \"PAYMENT_TOKEN\",\n      \"kind\": \"user\",\n      \"hasValue\": false,\n      \"createdAt\": \"2026-10-22T12:45:13.146Z\",\n      \"updatedAt\": \"2026-10-22T12:45:13.187Z\",\n      \"createdBy\": \"3f6c1a52-8b1e-4c7a-9d2f-5e0b7a4c1d93\",\n      \"updatedBy\": \"3f6c1a52-8b1e-4c7a-9d2f-5e0b7a4c1d93\",\n      \"updatedByName\": \"Anna Smith\"\n    },\n    \"state\": {\n      \"desiredRevision\": 0,\n      \"appliedRevision\": 0,\n      \"appliedServerId\": null,\n      \"status\": \"PENDING\",\n      \"failureCode\": null,\n      \"deliveredNames\": [],\n      \"serviceName\": null,\n      \"updatedAt\": \"2026-10-22T12:45:13.206Z\"\n    }\n  }\n}\n```\n\n## Error response example\n\n400 — the body contains a value:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SECRET_VALUE_NOT_ACCEPTED\",\n    \"message\": \"Set secret values in the application card.\",\n    \"applicationUrl\": \"\u002Fapplications?app=cmsw806qi0000tdskiw2aegii\"\n  }\n}\n```\n\n`error.applicationUrl` points to the application card, where the owner sets the value.\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `SECRET_VALUE_NOT_ACCEPTED` | The body has a `value` field, even an empty one. Set the value on the application card |\n| 400 | `SECRET_INVALID_NAME` | Invalid or reserved name, other than a system secret name |\n| 400 | `SECRET_INVALID_REQUEST` | Invalid request body: not JSON, no `name`, `name` is not a string, or there are extra fields |\n| 400 | `SECRET_LIMIT_REACHED` | The application already has 100 author names. System secrets are not counted |\n| 404 | `APPLICATION_NOT_FOUND` | The 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 |\n| 409 | `SECRET_ALREADY_EXISTS` | The name already exists. Its value and data stay unchanged |\n| 409 | `SECRET_SYSTEM` | A 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 |\n| 413 | `SECRET_BODY_TOO_LARGE` | The request body exceeds 128 KiB |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | Key not found |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | A read-only key cannot create names |\n| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | A Cowork subscription key with the `vibe:cowork` scope cannot create names |\n| 403 | `EXTERNAL_COLLABORATOR_KEY_SERVER_MISMATCH` | The external development member's key is not linked to a machine, and the application has no machine either |\n| 403 | `EXTERNAL_COLLABORATOR_NOT_A_MEMBER` | Key of an external development member whose membership on the machine was revoked or has expired |\n| 403 | `PORTAL_COLLABORATOR_NOT_A_MEMBER` | Key of a development team member who is no longer in the machine's team or is not linked to it |\n| 429 | `RATE_LIMIT_EXCEEDED` | The 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 |\n| 500 | `SECRET_OPERATION_FAILED` | The operation failed. The response does not include the original error |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Application secrets](\u002Fdocs\u002Fapplications\u002Fapp-secrets)\n- [List application secrets](\u002Fdocs\u002Fapplications\u002Fapp-secrets\u002Flist)\n- [Delete a secret](\u002Fdocs\u002Fapplications\u002Fapp-secrets\u002Fdelete)\n- [Application catalog](\u002Fdocs\u002Fapplications)\n","2026-11-05",{},1794739458963]