API tokens and service identities

An API token lets software use your account without a person signing in: a nightly export, a dashboard, a partner's system. Every token carries scopes, the same permissions an AI app asks for on the consent screen, so there is one permission model to learn. The full list is in AnswerStack MCP tools reference.

Tokens live in the Developer area: open the account menu (top right), choose Personal settings, then Developer.

Personal tokens#

A personal token acts as you. It never does more than you can, and it stops working if you leave the account or are deactivated.

1. Make it

   On Your tokens, press Make a token.

   

2. Fill it in

   Field	What to put
   Token name	What uses it, so you can tell tokens apart.
   What it may do	Tick only the scopes the job needs. Scopes your role cannot hold are greyed out.
   Which groups it may see	Every group I can see, or Only these groups. A group manager always picks from their own.
   Ends after	30 days, 90 days (the default) or 365 days. A personal token always ends.

3. Copy it now

   Press Make the token. The token is shown once. Copy it into your secret store straight away; if it is lost, revoke it and make another.

Personal tokens start with ans_pat_. The list shows only the start and the last four characters.

Service identities#

A service identity is for software, not a person: a warehouse job, a partner's system. It keeps working when the member who made it leaves. Only owners and admins can make one.

Press New service identity and fill in Name, What it is for and The most it may do. That last one is a role, and it is the ceiling for every token the identity gets. Only an owner can give an identity an owner's reach.

Disable stops every token and client the identity has, until you press Enable.

Service tokens#

On the identity, press Make a token. It is the same dialog as a personal token, with two differences:

• Ends after defaults to 365 days. Only an owner can choose Never.
• Allowed addresses is optional: up to 20 IP addresses, one per line. The token then works only from those.

Service tokens start with ans_svc_.

Machine OAuth#

Some partners' software expects OAuth rather than a fixed token. On the identity, press OAuth client, tick the scopes, and press Make the client. You get a Client ID and a Client secret, shown once, and the exact token address and resource to use.

The client asks for short-lived access tokens (15 minutes) with client_credentials, then uses them on AnswerStack's MCP server:

curl -sS -X POST "https://api.<your-domain>/oauth/token" \
  -u "$ANSWERSTACK_CLIENT_ID:$ANSWERSTACK_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource="https://api.<your-domain>/mcp" \
  -d scope="account:read calls:read"

The answer carries an access_token to send as Authorization: Bearer. Asking for scopes the client was not given does not fail; the token simply leaves them out.

An OAuth client is a connected app. While your account has turned connected apps off, or while AnswerStack support has suspended app access for your account, its tokens are refused on the MCP server with 403 access_denied. The identity's API tokens keep working on the REST API.

Where tokens work#

AnswerStack's MCP server, with any token, within its scopes. See AnswerStack MCP tools reference.

The REST API, on the routes below. Every other route refuses a token with 403: API tokens cannot be used here. Sign in to the app instead.

Some routes need several scopes together, because of what they return:

The call and callback lists leave out callers' names, numbers and reasons unless the token also has contacts:read.

Use a token#

Send it as a bearer token, exactly like a signed-in session:

curl -sS "https://api.<your-domain>/v1/account/calls?outcome=booked&limit=50" \
  -H "Authorization: Bearer ans_pat_..."

curl -sS -X POST "https://api.<your-domain>/v1/account/callbacks/$CALLBACK_ID/done" \
  -H "Authorization: Bearer ans_svc_..." \
  -H "content-type: application/json" \
  -d '{"note":"Called back, tour booked for Thursday."}'

A token missing a scope gets 403 with the code insufficient_scope, and the message names what it needs, for example This API token needs transcripts:read and contacts:read. Each token may make 60 requests a minute. The error format, pagination and other limits are in API authentication.

Revoking and expiry#

• Revoke on any list stops the token at once. Owners and admins can revoke any token from Every token.
• A week before a token ends, an email goes out: to the member for a personal token, to owners and admins for a service token.
• Deactivating a member revokes their personal tokens. Service tokens carry on.
• Each list shows when a token was last used, and from which address.
• Making and revoking tokens is recorded in the account's audit log, and so is every change a token makes.