For AI agents: markdown of this page — /docs-content-en/applications/connectors/access-request.md documentation index — /llms.txt

Request access to a connector

POST /v1/applications/:id/connectors/:slug/access-request

Sends the Bitrix24 account administrator a request to grant the application access to a company connector, and returns the connector with its current access state. No request body is required.

Parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionApplication card ID. Get it from: GET /v1/applications
Parameterslug (path) Typestring Requiredyes DescriptionConnector code. Get it from: GET /v1/applications/:id/connectors

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/applications/APPLICATION_ID/connectors/orders/access-request \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/applications/APPLICATION_ID/connectors/orders/access-request \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/applications/APPLICATION_ID/connectors/orders/access-request', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('State:', data.appState)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/applications/APPLICATION_ID/connectors/orders/access-request', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
console.log('State:', data.appState)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.slug Typestring DescriptionConnector code
Fielddata.title Typestring DescriptionConnector title
Fielddata.iconUrl Typestring / null DescriptionIcon URL; null for a connector from the company catalog
Fielddata.appState Typestring DescriptionApplication access state after the request: DISABLED_ON_PORTAL, NOT_CONNECTED, CONNECTION_BROKEN, NO_GRANT, GRANT_PENDING, GRANT_DENIED, GRANT_REVOKED, EXPOSURE_WIDENED or AVAILABLE
Fielddata.readTools Typearray DescriptionConnector read tools: name, title, description, inputSchema — as in the connector list
Fielddata.exposure.linkAccess Typestring DescriptionThe application's current link access: OFF, VIBECODE_AUTH, PUBLIC
Fielddata.exposure.externalApiEnabled Typeboolean DescriptionWhether the application's external API is enabled

Response example

JSON 
{
  "success": true,
  "data": {
    "slug": "orders",
    "title": "Orders",
    "iconUrl": "https://vibecode.bitrix24.com/api/connectors/orders/icon",
    "appState": "GRANT_PENDING",
    "readTools": [],
    "exposure": {
      "linkAccess": "OFF",
      "externalApiEnabled": false
    }
  }
}

Error response example

404 — the connector is unavailable or does not support connecting a company:

JSON 
{
  "success": false,
  "error": {
    "code": "CONNECTOR_NOT_FOUND",
    "message": "CONNECTOR_NOT_FOUND"
  }
}

Errors

HTTP Code Description
HTTP404 CodeCONNECTOR_NOT_FOUND DescriptionThe connector is unavailable or does not support connecting a company
HTTP404 CodeAPPLICATION_NOT_FOUND DescriptionThe application does not exist, is unavailable, is on a different server than the key, or connectors for applications are disabled for the portal
HTTP413 CodeFST_ERR_CTP_BODY_TOO_LARGE DescriptionThe request body is larger than 1 KiB
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in READONLY mode
HTTP403 CodeEXTERNAL_COLLABORATOR_KEY_SERVER_MISMATCH DescriptionThe external collaborator's key and the application are not bound to the same server
HTTP403 CodeEXTERNAL_COLLABORATOR_NOT_A_MEMBER DescriptionThe external developer's membership was revoked or has expired
HTTP403 CodePORTAL_COLLABORATOR_NOT_A_MEMBER DescriptionThe user is no longer a member of the server's development team
HTTP401 CodeINVALID_API_KEY DescriptionInvalid key
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key was not passed

Full list of common API errors — Errors.

Known specifics

  • Repeated request. While a request is pending or access is active, a repeated call does not create a new request and does not notify the administrator again. A denied or revoked request can be submitted again.
  • A request does not grant access. Access appears only after the administrator approves it. Before approving, the administrator connects the company to the connector, and until it is connected, appState after the request may remain NOT_CONNECTED.

See also