API Keys

Overview

You can authorize your access using the API keys. All API keys have the same permissions and full account access if not linked to an agent. You can optionally link an API key to an agent in the same workspace. When a key is linked:

Authorization identifies the agent for actions related to conversations and messages.
The API key access is limited to the Agent+ role permissions.

The API key can be added to the 'authorization' request header to authorize the request. Each API key has the following fields:

API key object

Each API key has the following fields

Attributes	Type	Description
`id`	`string`	The unique ID of the API key.
`label`	`string`	The label for this API key. May be duplicate with other labels.
`key`	`string`	The API key. The key is prefixed with `bck_`.
`createdAt`	`string`	The timestamp when this instance was created.
`agentId`	`string`	The ID of the agent if the key is linked to an agent.

In JSON Format

{
  "workspaceId": 12,
  "id": "67642054b6cc2888638e4600",
  "key": "bck_******************************",
  "label": "Dev API Key",
  "createdAt": "2024-12-19T13:32:04.009Z",
  "agentId": "507f1f77bcf86cd799439011"
}

GraphQL requests with an API key

Send the raw API key in the Authorization header (not Bearer …). Requests must include workspaceId in the operation variables.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Generate API Key API

This endpoint lets you generate an API key.

To get your first API key, visit API Keys (opens in a new tab) in the dashboard, choose a label, then save.

Attributes	Type	Description
`workspaceId`	`number`	The workspace ID.
`label`	`string`	Required. The label to assign to this API key. It may be duplicated with other labels.
`agentId`	`ID`	Optional. If set, the key is linked to this agent in the workspace. The agent must exist and belong to `workspaceId`.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

mutation genApiKey($input: ApiKeyGenInput!) {
  genApiKey(input: $input) {
    workspaceId
    id
    key
    label
    createdAt
    agentId
  }
}
 
input ApiKeyGenInput {
  workspaceId: Int!
  label: String!
  agentId: ID
}

The mutation above returns JSON structured like this:

{
  "data": {
    "genApiKey": {
      "workspaceId": 12,
      "id": "67642054b6cc2888638e4600",
      "key": "bck_******************************",
      "label": "Dev API Key",
      "createdAt": "2024-12-19T13:32:04.009Z",
      "agentId": "507f1f77bcf86cd799439011"
    }
  }
}

Programming language examples

curl 'https://gateway.bcrumbs.net/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  --data-raw $'{"operationName":"genApiKey","variables":{"input":{"label":"Dev API Key","workspaceId":12}},"query":"mutation genApiKey($input: ApiKeyGenInput!) {\\n  genApiKey(input: $input) {\\n    workspaceId\\n    id\\n    key\\n    label\\n    createdAt\\n  }\\n}"}'

List API Keys API

This endpoint returns API keys for a specific workspace.

Parameter	Type	Description
`workspaceId`	`number`	The workspace ID.
`label`	`string`	Optional. Filter by label.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

query apiKeys($input: ApiKeysInput!) {
  apiKeys(input: $input) {
    nodes {
      workspaceId
      id
      label
      createdAt
      agentId
    }
  }
}
 
input ApiKeysInput {
  workspaceId: Int!
  label: String
}

The query above returns JSON structured like this:

{
  "data": {
    "apiKeys": {
      "nodes": [
        {
          "workspaceId": 12,
          "id": "67642054b6cc2888638e4600",
          "label": "Dev API Key",
          "createdAt": "2024-12-19T13:32:04.009Z",
          "agentId": "507f1f77bcf86cd799439011"
        }
      ]
    }
  }
}

Programming language examples

curl 'https://gateway.bcrumbs.net/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  --data-raw $'{"operationName":"apiKeys","variables":{"input":{"workspaceId":12}},"query":"query apiKeys($input: ApiKeysInput!) {\\n  apiKeys(input: $input) {\\n    nodes {\\n      workspaceId\\n      id\\n      key\\n      label\\n      createdAt\\n    }\\n  }\\n}"}'

Delete API Key API

This endpoint lets you delete an API key.

Parameter	Type	Description
`workspaceId`	`number`	The workspace ID.
`id`	`string`	The ID of the API key to delete.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

mutation deleteApiKey($input: ApiKeyDeleteInput!) {
  deleteApiKey(input: $input) {
    workspaceId
    id
    label
    createdAt
    agentId
  }
}
 
input ApiKeyDeleteInput {
  workspaceId: Int!
  id: ID!
}

The mutation above returns JSON structured like this:

{
  "data": {
    "deleteApiKey": {
      "workspaceId": 12,
      "id": "67642054b6cc2888638e4600",
      "key": "e108d6e3-****-****-****-************",
      "label": "Dev API Key",
      "createdAt": "2024-12-19T13:32:04.009Z",
      "agentId": "507f1f77bcf86cd799439011"
    }
  }
}

Programming language examples

curl 'https://gateway.bcrumbs.net/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  --data-raw $'{"operationName":"deleteApiKey","variables":{"input":{"id":"6764755e282eb541bb8c9ec9","workspaceId":12}},"query":"mutation deleteApiKey($input: ApiKeyDeleteInput!) {\\n  deleteApiKey(input: $input) {\\n    workspaceId\\n    id\\n    key\\n    label\\n    createdAt\\n  }\\n}"}'

Broadcasts Webhooks