Create an API access token
Change · POST /v1/access-tokens · MCP tool issue-access-token
Creates a long-lived token for scripts and MCP clients. Send it in the X-Tarsana-Access-Token header. The token is shown only once, so copy it now; if you lose it, create a new one and revoke the old one. A token cannot create, list or revoke tokens, and it expires at expires_at. You need to be signed in with a session to create one.
Roles that can call it: viewer, builder, deployer.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
token_label | body | no | Optional: a name for this token, so that you can tell your tokens apart |
Returns
A JSON object with these keys: access_token, token_id, token_label, login, carrier, scopes, tenants, issued_at, expires_at, guarantee, caller_authenticated.
Example request
curl -X POST https://api.tarsana.io/v1/access-tokens \
-H "X-Tarsana-Session: $SESSION" \
-H "Content-Type: application/json" \
--data '{"token_label": "laptop-mcp"}'Example response
{
"access_token": "YOUR-ACCESS-TOKEN",
"token_id": "67e94a06c977c24c",
"token_label": "laptop-mcp",
"login": "you@example.com",
"carrier": "X-Tarsana-Access-Token",
"scopes": [
"operate",
"read",
"submit"
],
"tenants": [
"acme"
],
"issued_at": "2026-10-05T02:15:39Z",
"expires_at": "2027-01-03T02:15:39Z",
"guarantee": "namespaces are separated, callers are not authenticated",
"caller_authenticated": false
}Errors
| Code | HTTP | What it means |
|---|---|---|
invalid_parameter | 400 | A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again. |
unauthenticated | 401 | Your request has no credential, or one that Tarsana does not recognise. Sign in with login, or send a valid access token. |
forbidden | 403 | Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them. |
rate_limited | 429 | You sent too many requests in a short time. Wait for the number of seconds in retry_after_seconds, then try again. |
surface_fault | 500 | Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening. |