Create an application

POST /v1/apps

Registers an OAuth application in your Bitrix24 account and creates a paired API key. The body is passed flat, without a wrapper.

Request fields (body)

handlerUrl is set by the platform — it is not accepted in the body. OAuth callbacks and opening a placement go through it. For the difference between appUrl and handlerUrl, see the Applications section.

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/apps \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales dashboard",
    "scopes": ["crm", "user", "placement"],
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com"
  }'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/apps \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales dashboard",
    "scopes": ["crm", "user", "placement"],
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/apps', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Sales dashboard',
    scopes: ['crm', 'user', 'placement'],
    appUrl: 'https://app-abc12345.vibecode.bitrix24.com',
  }),
})

const { data } = await res.json()
// Save data.rawKey immediately — it is returned only once
console.log('App ID:', data.id)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/apps', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Sales dashboard',
    scopes: ['crm', 'user', 'placement'],
    appUrl: 'https://app-abc12345.vibecode.bitrix24.com',
  }),
})

const { data } = await res.json()

Response fields

Response example

rawKey is shown with a truncated secret — this is not a working value.

{
  "success": true,
  "data": {
    "id": "33c4d5e6-f7a8-49b0-1234-5c6d7e8f9012",
    "title": "Sales dashboard",
    "description": null,
    "scopes": ["crm", "user", "placement"],
    "handlerUrl": "https://vibecode.bitrix24.com/v1/bitrix-handler",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com",
    "redirectUris": [
      "https://vibecode.bitrix24.com/oauth/complete",
      "http://localhost"
    ],
    "bitrixClientId": "local.7c3d4e5f6a7b80.55556666",
    "authorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "authorBitrixUserId": 42,
    "authorBitrixUserIdSource": "member",
    "portalId": "8b1f0e2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "createdAt": "2026-06-24T09:12:45.781Z",
    "updatedAt": "2026-06-24T09:12:45.781Z",
    "placements": [],
    "catalogStatus": "PRIVATE",
    "publishedAt": null,
    "mobile": false,
    "rawKey": "vibe_app_local_7c3d4e5f6a7b80_55556666_…_6666"
  }
}

Error response example

400 — validation failed:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Required"
  }
}

Errors

The full list of general API errors — Errors.

Known specifics

• The platform reports non-ASCII characters lost from the title. A value sent without explicit UTF-8 serialization arrives with question marks instead of letters: the bytes are lost on the client side, before the request is sent. Windows PowerShell sends values this way. The application is still created as is, and the response carries warnings naming the field — the title becomes the Bitrix24 catalog card name on publish, so fix it right away. A ready-to-run call with UTF8.GetBytes — Windows / PowerShell and UTF-8.
• The authorization key is returned only once. The rawKey field is present in the creation response and nowhere else — neither in application data nor in the list. If you did not save it at creation, recreate the application.
• A pair is created: an application and an API key. Registration creates an application record and a paired authorization key in one step. This affects deletion: the key frees a slot in the per-user limit only after deleting the application.
• Application scopes and paired-key scopes are different sets. In scopes you declare access to Bitrix24 account data — crm, user, placement. If the calling key's rights set is not fixed, the paired key receives that set plus four platform scopes: vibe:infra — servers and agents, vibe:ai — model calls, vibe:search — web search and research, vibe:storage — object storage. The authorization key can then create servers through POST /v1/infra/servers right away, even though vibe:infra was never in the create body. The data.scopes field of the response shows the application declaration, not the key's effective set — read the effective set from data.scopes of GET /v1/me called with that key.
• A key with a fixed rights set grants the paired key exactly what was declared. The rights set is fixed for a partner key, for a Cowork project key, for a personal key issued by the Vibecode dashboard form and for a key issued with exactScopes: true — Management keys. An application created with such a key gets a paired key holding exactly what is listed in scopes — no platform scopes are added to it. If you need infrastructure, list vibe:infra in scopes at creation time, otherwise POST /v1/infra/servers answers 403 INFRA_SCOPE_REQUIRED. The same goes for vibe:ai, vibe:search and vibe:storage. You can only declare a right that the calling key itself holds, otherwise the answer is 403 SCOPE_GRANT_REQUIRES_CONSENT. Adding the right later through updating the application does not work: vibe:* propagation never reaches a key with a fixed set.
• You can identify a key with a fixed rights set before creating the application. Call GET /v1/me with the key you plan to create the application with. The set is fixed when data.scopes matches what was ticked when the key was issued. Other keys carry vibe:ai and vibe:search in the set even when those were not ticked.
• The mobile flag can only be set at creation. Bitrix24 has no method for updating a local application, so PATCH /v1/apps/:id does not accept mobile — a sent value is ignored, see Update an application. For an existing application, turn the flag on in the application card on the Bitrix24 account, or create the application again.
• The mobile flag may not be applied at registration. When the Bitrix24 account registers the application through a path that cannot carry the flag, the application is still created, data.mobile is false in the response, and warnings carries a line starting with mobile:. In that case, turn the flag on in the application card on the account.

See also

• Applications
• Update an application
• Delete an application
• Publish
• Scopes
• Keys and authorization
• Rights to create keys and apps