Service identities

Every call needs Authorization: Bearer <key>. 3 calls:

• List service identities: GET /v1/service-identities
• Create a service identity for an MCP client: POST /v1/service-identities
• Rename, re-scope, limit or disable a service identity: PATCH /v1/service-identities/:id

List service identities

GET /v1/service-identities

MCP clients and the identities of AI agents, newest first. Tokens are never shown again.

Query parameters

Name	Type	Required	Description
limit	integer	No	From 1 to 100. Default 50.
cursor	string	No	Opaque cursor from next_cursor. Up to 512 characters.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
data	object[]
data[].allowed_line_ids	string[]
data[].api_key_id	string or null	API key id (key_...).
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].daily_limit	integer or null	From 0 to 9007199254740991.
data[].env	enum or null	One of: live, test.
data[].id	string (uuid)
data[].kind	enum	One of: ai_agent, mcp_client.
data[].name	string
data[].scopes	enum[]
data[].status	enum	One of: active, disabled.
next_cursor	string or null	Pass as cursor to get the next page; null at the end.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Create a service identity for an MCP client

POST /v1/service-identities

Returns the bearer token once, in token. It is an API key linked to the identity: the identity gets the scopes both allow, sends only from its lines and at most daily_limit messages a day. Rotate or revoke it through /v1/api-keys.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
allowed_line_ids	string[]	No	Up to 500 items.
daily_limit	integer or null	No	From 1 to 100000.
env	enum	No	One of: live, test. Default "live".
kind	enum	No	AI agent identities are made with their agent (POST /v1/agents). One of: mcp_client. Default "mcp_client".
name	string	Yes	Up to 80 characters.
scopes	enum[]	Yes	Up to 3 items.

Response 201

Field	Type	Description
allowed_line_ids	string[]
api_key_id	string or null	API key id (key_...).
created_at	string (date-time)	ISO 8601 timestamp.
daily_limit	integer or null	From 0 to 9007199254740991.
env	enum or null	One of: live, test.
id	string (uuid)
kind	enum	One of: ai_agent, mcp_client.
name	string
scopes	enum[]
status	enum	One of: active, disabled.
token	string	Shown once. Use as a bearer token for the API or MCP.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Rename, re-scope, limit or disable a service identity

PATCH /v1/service-identities/:id

Disabling stops its token at once. Changing scopes changes its token’s scopes too. AI agents’ identities change only through their agent.

Path parameters

Name	Type	Required	Description
id	string (uuid)	Yes

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
allowed_line_ids	string[]	No	Up to 500 items.
daily_limit	integer or null	No	From 1 to 100000.
name	string	No	Up to 80 characters.
scopes	enum[]	No	Up to 3 items.
status	enum	No	One of: active, disabled.

Response 200

Field	Type	Description
allowed_line_ids	string[]
api_key_id	string or null	API key id (key_...).
created_at	string (date-time)	ISO 8601 timestamp.
daily_limit	integer or null	From 0 to 9007199254740991.
env	enum or null	One of: live, test.
id	string (uuid)
kind	enum	One of: ai_agent, mcp_client.
name	string
scopes	enum[]
status	enum	One of: active, disabled.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.