Skip to content
Help Center
Submit a request Sign in

Create and manage API tokens

API tokens let an approved integration authenticate as a selected Supportbench agent. Use a separate, clearly owned credential for a reporting job or other supported API connection so its access, expiry and replacement are understandable. In B2B support, the integration must respect the same customer and operational boundaries as the identity it uses; creating a token does not grant a new set of business permissions.

Applies to: Supportbench Core. Location: Settings → API → API Tokens. Listing, creating and revealing tokens require Administer API configurations. The selected agent’s access also governs the integration’s supported operations.

Before you begin

  • Identify the integration, its business owner, the records it needs and the operations it must perform. A reporting job and a case-writing integration may need different access.
  • Confirm Administer API configurations permission and availability of the API Tokens editor. Do not ask an ordinary agent to reveal credentials they are not permitted to administer.
  • Review the selected active agent’s role and customer/Division access. Use an appropriate existing integration identity according to your organization’s policy; a token is not a way to bypass record access.
  • Prepare the destination’s protected credential storage and a planned replacement date. Keep the actual token out of articles, screenshots, Cases, email and shared logs.
  • If replacing a working credential, identify all consumers first and plan a controlled change. Revoking a token immediately interrupts consumers still using it.

Configure and verify

  1. Open Settings → API → API Tokens and choose New Token.
  2. Enter Name and an optional Description. Identify the integration and its owner without putting the secret or private customer data in these fields.
  3. Select the intended active Agent. Confirm this is the identity whose permissions the integration should use; the binding cannot be edited after creation.
  4. Set Expires deliberately. An explicitly selected date is a cutoff at 00:00 UTC at the start of that date, not the end of the day. Plan replacement before that instant. Leaving the date blank uses the current ten-year fallback; it is not a recommendation to leave credentials unmanaged.
  5. Choose Save Changes. A successful save returns to the token list; it does not automatically reveal the credential.
  6. Reopen the saved token. Use Reveal or Copy to obtain the value through the supported control, then put it directly into the intended integration’s protected credential setting. Do not paste it into an ordinary note to transfer it.
  7. Follow the linked REST API reference for the requested operation and authentication format. Documentation examples should use a placeholder such as YOUR_SUPPORTBENCH_TOKEN, never a working secret.
  8. Run a minimal approved request and verify the expected records and scope. Where a negative access check is needed, use a controlled test that does not send customer messages or change production records.
  9. Record the integration owner, agent identity, purpose, planned rotation and expiry separately from the secret. For a replacement, switch each consumer, verify its normal operation, then revoke the obsolete token and confirm those consumers no longer depend on it.

Settings reference

Token details

SettingWhat it controlsHow to choose
NameRequired operational label, up to 50 characters.Use a distinct name for the integration and environment so an administrator can identify it later.
DescriptionOptional explanation, up to 250 characters.Record the purpose and responsible owner; never store the token value here.
AgentActive agent used as the integration identity. Immutable after creation.Review the agent’s actual role and access before issuing the credential.
ExpiresExplicit dates expire at 00:00 UTC at the start of the selected date. Blank uses the current ten-year fallback. Immutable after creation.Choose a cutoff your team can meet and rotate before it. Dates beyond 2037 are clamped by token generation to 2037-12-31 00:00 UTC.
Reveal / CopySupported controls on the saved token record for obtaining its secret; routine display is masked.Reopen after saving and transfer only to the approved protected credential destination.
RevokeImmediately invalidates the token.Coordinate normal replacement first; if it is exposed, follow your incident process and review affected consumers.

Behavior to know

  • Changing the Agent or expiry requires a replacement token; renaming the record does not change those immutable values.
  • A valid credential is not proof that the agent may access every record or perform every operation. Authentication and authorization are separate checks.
  • No end-of-day grace period should be inferred from a selected date. Schedule rotation before the UTC cutoff and account for your local timezone.
  • The new-token save returns to the list. Reopen the saved row to Reveal or Copy; do not create repeated tokens because no secret appeared automatically.

Recommended use

  • Use a separate, named token per independently managed integration when appropriate. It makes ownership and replacement easier to coordinate than sharing one unexplained credential across many consumers.
  • Keep a credential inventory containing purpose, owner, bound agent, expiry and dependent jobs. Store the secret in the approved secret manager, separate from that ordinary inventory.
  • Review access when an integration changes purpose or the bound agent’s role changes. A token that was suitable for one workflow is not automatically suitable for a broader one.
  • Verify the new credential with the actual consumer before normal revocation of the old one. A successful manual read alone does not prove a scheduled job has switched its stored value.
  • For suspected exposure, use your security response process to revoke and replace promptly, investigate usage with the appropriate administrators, and remove leaked values from accessible material. Do not publish them as troubleshooting evidence.

Worked example: a weekly account-review integration

  1. The operations team needs an approved job to retrieve the data used in weekly customer reviews. It identifies the required records and selects an agent whose role is appropriate for that scope.
  2. An API administrator creates a clearly named token, sets a planned expiry, saves it, reopens the row and copies the secret into the job’s protected setting.
  3. The owner runs a small approved test and verifies the returned customer scope. They do not infer access correctness simply from a successful authentication response.
  4. The team records ownership and a rotation reminder. Before expiry, it creates a replacement, updates the job, verifies the next run and then revokes the old credential.
  5. If the job fails later, the owner checks the saved credential, UTC expiry, revocation and bound-agent access before repeatedly issuing new tokens.

Troubleshooting

ProblemWhat to check
I saved a token but did not see its valueReopen the saved row and use Reveal or Copy. Saving returns to the list; first confirm the record exists before creating another.
API Tokens or Reveal is unavailableCheck Administer API configurations and account/editor availability. Permission to work Cases is not API-administration permission.
Authentication failsCheck that the intended token was copied completely into the correct credential field and is not expired or revoked. Follow the API reference for the authentication format; do not disclose the token while seeking help.
Authentication works but an operation is deniedReview the selected agent’s active status, role, tenant and record access and the endpoint’s requirements. A token does not expand authority.
The token stopped working on the selected dateAn explicit date expires at its start, 00:00 UTC. Compare the current time in UTC and use the planned replacement process.
I need to change Agent or ExpiresCreate and verify a replacement; these values are immutable on the existing token.
An integration stopped after revocationDetermine which consumer still used the revoked value. Install an authorized replacement and verify the job; do not assume another consumer’s successful test covered this one.
A distant expiry was shortenedToken generation clamps years beyond 2037 to 2037-12-31 00:00 UTC. Use a manageable rotation schedule; a later date shown on the saved record does not extend that effective cutoff.
  • Organization → Configure agent roles and division access
  • API → Find API IDs for queues, statuses, agents and custom-field choices
  • API → Connect AI clients with MCP access

Was this article helpful?