API Tokens

Manage your workspace's API tokens programmatically. For how to use tokens, see Authentication.

The token object

{
  "id": 3,
  "name": "Zapier integration",
  "permissions": ["contacts:read", "contacts:write"],
  "last_used_at": "...",
  "expires_at": null,
  "created_at": "...",
  "updated_at": "..."
}

Endpoints

Method	Path	Permission	Description
GET	/api-tokens	api_tokens:read	List tokens (paginated)
POST	/api-tokens	api_tokens:write	Create a token
GET	/api-tokens/permissions	api_tokens:read	Every available permission
GET	/api-tokens/{id}	api_tokens:read	Get a token
PUT	/api-tokens/{id}	api_tokens:write	Update the name, permissions or expiry
DELETE	/api-tokens/{id}	api_tokens:write	Revoke a token. Returns 204.

List tokens

GET /api-tokens returns only tokens belonging to the authenticated token's workspace.

Parameter	Type	Default	Description
page	integer	1	Page number, starting at 1
per_page	integer	15	Results per page, from 1 to 100
search	string		Partial token name
permission	string		A permission returned by GET /api-tokens/permissions
sort	string	created_at	name, last_used_at, expires_at, created_at or updated_at
direction	string	desc	asc or desc

GET /api/v1/api-tokens?search=zapier&permission=contacts%3Aread&sort=name&direction=asc&per_page=15

The response follows the pagination contract. Equal sort values are ordered consistently by token ID.

Create a token

{
  "name": "Zapier integration",
  "permissions": ["contacts:read", "contacts:write"],
  "expires_at": "2027-01-01T00:00:00Z"
}

Field	Rules
name	Required. Max 255 characters
permissions	Required. At least one value from GET /api-tokens/permissions
expires_at	A date in the future. Leave it out for a token that never expires

201

{
  "data": { "id": 4, "name": "Zapier integration", "token": "Xk3...48 chars", "permissions": ["contacts:read", "contacts:write"] },
  "message": "Token created successfully. Make sure to copy it now..."
}

WARNING

The plain token appears only in this response. Beeving can't show it to you again.