Create and manage API tokens

Updated Monday, October 26, 2026 · Marc Staine

API tokens give an integration authenticated access through a selected agent. Bind each token to an appropriate agent, set a deliberate expiry and keep the secret out of articles, tickets and shared logs.

Applies to: Supportbench Core. Location: Settings → API → API Tokens. Access and available controls depend on your role and account capabilities.

Before you begin

You need permission to edit this configuration. Ask an administrator if the page is available but its editing controls are not.
Review the current configuration and where it is used before making a change. Available choices depend on your account, enabled modules, division access and role.
Use a test record or a controlled test account for behavior checks. Do not change production routing or send customer messages just to try an example.

Configure and verify

Open Settings → API → API tokens.
Create a token with a clear name, description, active agent and explicit expiry.
Copy the secret through the provided flow into the intended integration’s protected credential storage.
Test a minimal permitted API request and an operation the identity should not be allowed to perform.
Record ownership and rotation details separately from the secret. Revoke obsolete tokens after replacement is verified.

Settings reference

Token details

Setting	What it controls	How to choose
Name / Description	Name up to 50 and description up to 250 characters.	Identify the integration and responsible owner without storing the secret.
Agent	Active agent whose supported access is used; binding is immutable after creation.	Choose the intended integration identity and review its role.
Expiry	Token expiration; a blank value uses the current ten-year fallback. Immutable after creation.	Choose an explicit date appropriate to your rotation process.
Token value	Secret exposed through the supported creation/reveal flow and otherwise masked.	Store it in your integration’s secret store.
Revoke	Invalidates the token immediately.	Coordinate replacement first when an active integration depends on it.

Behavior to know

A token is a credential, not a documentation example. Never paste a real token into a public guide or screenshot.
Changing the bound agent or expiry requires a replacement token rather than editing those immutable fields.
Before using a token, confirm that the bound active agent’s role permits the intended API operations. A token does not grant additional role permissions.

Recommended use

Use terminology that agents and customers already understand. Explain the intended meaning in the description.
Keep the initial configuration small enough for people to choose consistently. Add options when they represent a real operational difference.
Review existing references before renaming, changing scope, or deleting. Where supported, deactivate an obsolete option before considering permanent deletion.

Worked example

Create a dedicated token for a reporting integration using an appropriately restricted agent.
Verify the integration can read its required records.
Confirm it cannot perform unrelated writes and record a planned rotation date.

Troubleshooting

Problem	What to check
The item is missing from a picker.	Check Active, division access, parent hierarchy, enabled modules, and the user’s role. Reopen the consuming form after saving.
The form rejects a save.	Read the displayed validation message. Check required values, text limits and permitted scope; do not change unrelated settings to bypass validation.
An existing record still shows an old value.	A configuration change and a record change are different operations. Inspect the record and relevant references before assuming the save failed.

Organization → Configure agent roles and division access
API → Find record IDs for API configuration
API → Connect AI clients with MCP access

Supportbench REST API introduction

Was this article helpful?