#Key self-description

GET /v1/me

Returns a self-description of the key that made the request: its type, the bound portal, the tariff and the platform capabilities available on the portal. No scope is needed — the endpoint responds to any valid key and serves as the AI model's starting point for getting acquainted with the portal.

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 a portal entity. 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 indicates for which key the block is present.

If you are getting to know the key for the first time, 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 portal data. Description — Management keys.

#Response example

Personal key (vibe_api_) — main fields shown:

{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.com",
    "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, the endpoint returns the full text.

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

{
  "success": true,
  "data": {
    "type": "oauth_app",
    "portal": "mycompany.bitrix24.com",
    "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 account 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 mandatory 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:

Copy

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 tariff no more than once per minute. The parameter forces a live check of the portal's tariff in Bitrix24 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 portal.

The response is cached server-side for about 30 seconds. A change of scopes or access mode is reflected in the response immediately. The tariff, 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 a fresh tariff.

For a key in read-only mode, six capabilities slots arrive closed. They are apps.create, apps.publish, apps.bindPlacements, servers.create, agents.create and managedBots.create — all six return available: false and reason: "WRITE_BLOCKED_READONLY_KEY". The remaining slots, including servers.deploy, servers.preview, servers.wake and both aiRouter operations, are not affected by the access mode. More — Access mode.

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.

#See also

• Creating and using a key
• API reference for the model
• Access mode
• Scopes
• Management keys
• Errors