Key self-description

GET /v1/me

Returns a self-description of the key that made the request: its type, the bound Bitrix24 account, that account's plan and the platform capabilities available on it. No scope is needed — the endpoint responds to any valid key and serves as an AI model's starting point for exploring the Bitrix24 account.

The response shape depends on the key type. How the key is passed in the request — Passing the key.

Parameters

Examples

curl — personal key

curl https://vibecode.bitrix24.com/v1/me \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl https://vibecode.bitrix24.com/v1/me \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/me', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Key type:', data.type, '· portal:', data.portal)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/me', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

The response describes the key, not an entity on the Bitrix24 account. The top-level data.* blocks are a capability map: some blocks are common to all keys, some appear only for a key of a certain type. The "Key type" column shows which key types each block appears for.

If this is your first look at the key, four blocks are enough. type tells you which key you are working with. scopes — which data you have access to. accessMode — whether writing is allowed. capabilities — which operations are available on this Bitrix24 account and why the rest are denied. The other blocks are needed for a specific task: deployment and infra when working with servers, ai and webSearch when calling models, storage when uploading files.

The management key (vibe_live_) returns a different set of blocks — portals, totalAppKeys, a reduced capabilities — and carries no Bitrix24 account data. Description — Management keys.

Response example

Personal key (vibe_api_) — main fields shown:

{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.com",
    "portalId": "8c3d1e04-…",
    "tariff": {
      "code": "en_basic",
      "name": "Basic",
      "isCommercial": true,
      "wasEverCommercial": true,
      "checkedAt": "2026-07-08T08:57:58.270Z",
      "kind": "CLOUD"
    },
    "scopes": ["crm", "task", "tasks", "im", "imbot", "disk", "user"],
    "accessMode": "READWRITE",
    "capabilities": {
      "apps": {
        "create": { "available": true },
        "publish": { "available": true },
        "bindPlacements": { "available": true }
      },
      "servers": {
        "create": { "available": true, "reason": "COMMERCIAL" },
        "deploy": { "available": true, "reason": "COMMERCIAL" },
        "preview": { "available": true },
        "wake": { "available": true }
      },
      "agents": {
        "create": {
          "available": true,
          "reason": "COMMERCIAL",
          "note": "Agent servers count toward the portal's infrastructure limit (currently 2/10)."
        }
      },
      "managedBots": {
        "create": {
          "available": true,
          "reason": "COMMERCIAL",
          "note": "Managed bot servers count toward the portal infrastructure limit."
        }
      },
      "aiRouter": {
        "chatCompletions": { "available": true },
        "byok": { "available": true }
      }
    },
    "owner": { "name": "John Brown", "userId": "1" },
    "expiresAt": null
  }
}

The apps.publish and apps.bindPlacements slots always carry a note — it is omitted from the example above, but the endpoint returns the full text.

Authorization key (vibe_app_) without a session token — showing the blocks a personal key does not have:

{
  "success": true,
  "data": {
    "type": "oauth_app",
    "portal": "mycompany.bitrix24.com",
    "portalId": "8c3d1e04-…",
    "accessMode": "READWRITE",
    "app": { "title": "CRM Dashboard", "id": "f2342f7a-…" },
    "currentUser": null,
    "placements": {
      "available": true,
      "registered": ["LEFT_MENU"],
      "endpoints": [
        "POST https://vibecode.bitrix24.com/v1/placements/bind",
        "POST https://vibecode.bitrix24.com/v1/placements/unbind",
        "GET https://vibecode.bitrix24.com/v1/placements",
        "GET https://vibecode.bitrix24.com/v1/placements/available"
      ],
      "bindPrerequisite": {
        "subscriptionRequired": false,
        "note": "Binding a placement requires a Bitrix24-side prerequisite: the portal must be on a commercial Bitrix24 plan…",
        "errorCodes": [
          "INT_TARIFF_REQUIRED",
          "BITRIX_UNAVAILABLE"
        ]
      }
    }
  }
}

oauth.authorizeUrl is a template, not a ready-made link. The /v1/oauth/authorize endpoint requires the state parameter (16–512 characters) — a CSRF token per RFC 6749 §10.12 that the client generates: create a cryptographically random string, add it to the URL, and verify the value returned in the callback. The server cannot generate state for you — otherwise CSRF protection does not work. Opening authorizeUrl as is returns 400 INVALID_REQUEST "state: Required". Optionally add redirect_uri (your callback address — without it the built-in /oauth/complete page is used) and scope. Full-link example:

Copiar

https://vibecode.bitrix24.com/v1/oauth/authorize?app_key=vibe_app_…&state=aAbBcCdDeEfFgGhH&redirect_uri=https://myapp.com/callback

Error response example

401 — invalid key:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

?refresh=tariff checks the plan no more than once per minute. The parameter forces a live check of the Bitrix24 account plan and resets the response cache. If the previous check was less than a minute ago, the request returns the already known value without a new check. For a management key the parameter does nothing — such a key is not bound to a Bitrix24 account.

The response is cached server-side for about 30 seconds. A change of scopes or access mode is reflected in the response immediately. The plan, balance and infrastructure state are updated on the first read after the cache expires. A request with ?refresh=tariff resets the cache, and the next read without this parameter returns an up-to-date plan.

For a key in read-only mode, nine capabilities slots come back closed. They are apps.publish, apps.bindPlacements, servers.create, servers.deploy, servers.wake, agents.create, managedBots.create and both aiRouter operations — all nine return available: false and reason: "WRITE_BLOCKED_READONLY_KEY". For a read-only key the response root also carries writeRestriction — the WRITE_BLOCKED_READONLY_KEY code, the scope it applies to, and a link to the access-mode page. The field is present only while the restriction is in force: a platform administrator may lift it, and then the field disappears from the response along with the restriction itself. Inside the field an exceptions list names the routes that check the mode themselves and therefore partly succeed; today that is POST /v1/apps, where a read-only key creates an application in the same mode, plus two non-GET addresses that are not writes: DELETE /v1/cowork/key (emergency key revocation) and DELETE /v1/infra/servers/{id}/lock (releasing a stuck lock, pointed at by the recoveryAction field of an EXEC_BUSY response). A management key carries the field too, but nothing lifts it there: the write block for such keys is unconditional. The field exists because the response names writing endpoints in some thirty places (storage, feedback, source-storage and cowork hints): those are addresses, not permissions. Per-operation availability is in capabilities.

apps.create does NOT come back closed: such a key can create an application in READONLY mode, and the ban on READWRITE is spelled out in that slot's note field. Reads are not affected by the mode — servers.preview, for one. More — Access mode.

The plan name is for display, not for comparison. The data.tariff.name field is assembled at read time and can change without the plan itself changing. The platform picks it in this order. If the plan code is known to the edition catalog — from there, in English. Otherwise the license name as Bitrix24 reported it, in the account's language. Otherwise the previously stored name. Otherwise null. Three things follow. First, null is a normal value, not an error. Second, the name does not depend on who asks — neither Accept-Language nor the key owner's interface language changes it. Third, the plan code is never substituted for the name — when there is no name, you get null, not pro100. Branch your logic on data.tariff.code, isCommercial, and kind. The labels of known editions have also been refined — three of them: the demo edition is now Trial period, Project is now Project — legacy free, and NFR is now NFR — partner licence.

The wasEverCommercial flag is not one-way. A plan downgrade does not withdraw trust: the switch to a free plan does not clear the value by itself. Yet the flag is not one-way — the platform brings it in line with the facts when no grounds for it are found, and that has already happened on both cloud and self-hosted portals. Do not build logic on this field that assumes the transition can only go one way — check capabilities in the same response instead.

The downward correction does not reach every account. The flag is kept when the account has a completed payment behind it, when it moved from a trial period to a paid plan, or when the license region of a self-hosted account could not be determined. That last case is not a failure — trust is not withdrawn over a state that was not read in full. See Connecting a self-hosted Bitrix24.

Determine the placement model from the deployment block, not from the account plan. On the free Bitrix24 plan a new galaxy is not created. When Galaxy mode is enabled but there is no host, deployment.galaxyApp is absent, deployment.primary is standalone, and deployment.placementNote describes the two-step path. It is available only while capabilities.servers.create.available in the same response is true; select an allowed plan ID from capabilities.servers.create.limits.allowedPlans. When Galaxy mode is disabled, placementNote is absent, a one-shot request carrying source returns 400 SOURCE_AT_CREATE_GALAXY_ONLY, and the same capabilities slot decides whether the two-step path is available. When an existing host passes the advisory stored-state check, the galaxyApp block is present and a one-shot create carrying source is worth trying. This is not a guarantee: only POST /v1/infra/servers checks live capacity.

When an existing host fails the advisory check, the galaxyApp block is absent. While capabilities.servers.create.available is false, placementNote rules out a two-step dedicated-machine create: with trial enforcement active, the occupied slot returns 402 TRIAL_PORTAL_LIMIT. To retry one-shot creation, wait for the host to recover, ask an administrator to repair it, or upgrade the plan. After removing the host, re-read GET /v1/me and use the two-step path advertised there. Follow the hint in the actual POST response. The call sequence — Create a server and Deploy API.

Without a key in a browser the endpoint returns HTML. A GET /v1/me request without the X-Api-Key header and with the Accept: text/html header returns a stub page with status 200, not JSON. A request with a key or without text/html in the Accept header always gets the JSON self-description.

Scope requirements map

Until now the only way to learn a key's boundary was to make the call: the request went out and came back with a 403 SCOPE_DENIED refusal naming the missing scope. The list of available entities showed only what was open, while what was closed was simply absent — and absence alone could not distinguish "no such entity in the product" from "it exists but your key cannot reach it".

The data.api.scopeRequirements block answers that before the call:

{
  "granted": { "bitrix24": ["imbot"], "platform": ["vibe:ai", "vibe:search"] },
  "missing": {
    "bitrix24": {
      "crm": {
        "entities": ["deals", "contacts", "companies", "leads"],
        "unlocks": ["/v1/duplicates/find", "/v1/addresses"],
        "unlocksRemaining": 41,
        "truncated": true,
        "howToObtain": "reissue-key"
      }
    },
    "platform": {}
  }
}

Bitrix24 binds its scopes to a key when the key is issued, so their howToObtain is reissue-key: adding a scope in the settings of an already-issued key is not enough; the key has to be reissued. Vibecode scopes are edited in your Vibecode account.

The map describes the platform-side scope check only. It does not promise the call will succeed. A scope granted in your Vibecode account after the key was issued shows up in the map, but Bitrix24 does not honour it and answers BITRIX_ACCESS_DENIED. Refusals by key kind, ownership, read-only mode, account freeze and plan are separate axes and are not described in the map. The _note field inside the block carries the same warning.

Path coverage is not complete yet, and the map says so itself. A coverage.paths value of partial means some custom routes still lack a machine-checked verdict, so unlocks and unlocksRemaining under-report. Absence of a path from the list does NOT prove the path is ungated: if a call still answers with a scope refusal, trust the refusal, not the map. The entity list is always complete.

The refusal has not changed: a call without the required scope still returns 403 SCOPE_DENIED naming that scope. The map is a pre-flight check, not a replacement for the refusal.

See also

• Keys and authorization
• API reference for the model
• Access mode
• Scopes
• Management keys
• Errors