Minting API Tokens – Sapience Cloud

Overview

If you build against Sapience, you don't want to type a password every time your script runs. An API token (also called an API key) is a long-lived pass that lets your code act as you: it carries the same permissions, the same organisation and the same role you have when you sign in. You create it once, store it safely, and your scripts use it until it expires or you delete it.

There are two ways to create one:

	Your own token (user scope)	A token for someone in your organisation (org scope)
Who can do it	Anyone with a Sapience account	Organisation admins
Whose permissions it carries	Yours	The person you create it for
How long it can last	Up to 3 months (organisation admins: up to 24 months)	1 to 24 months

Creating tokens is done through the Sapience API. There is no screen for it in the app today.

Before You Start

Sign in normally first. Tokens are created from a normal sign-in session. A long-lived token can never create another token, so you can't renew a token with itself. When one is about to expire, sign in again and create a new one.

Your account must be in good standing. The same checks that apply when you sign in apply when a token is created: an inactive account or a lapsed licence can't create one.

Months are 30 days. A "3 month" token lasts 90 days.

Get a sign-in token with your username and password (replace the address with the one you use to reach Sapience):

curl -X POST "https://<your-sapience-address>/api/user/token" \
  -d "grant_type=password" \
  -d "username=<your-username>" \
  -d "password=<your-password>"

The reply contains an access_token. Use it in the steps below as <sign-in-token>.

Create Your Own Token (User Scope)

curl -X POST "https://<your-sapience-address>/api/admin/long-lived-tokens" \
  -H "Authorization: Bearer <sign-in-token>" \
  -H "Content-Type: application/json" \
  -d '{"number_of_months": 3, "name": "Nightly report script"}'

Field	What it means
`number_of_months`	How long the token lasts, in whole months. Most users: 1 to 3. Organisation admins: 1 to 24.
`name`	Optional label so you can tell your tokens apart later (up to 255 characters).

You get back your username, the expiry date and the token itself:

{
  "success": true,
  "data": {
    "username": "your-username",
    "expiry_timestamp": "2026-12-28T00:00:00Z",
    "token": "eyJhbGciOi..."
  }
}

Copy the token now. It is shown once and Sapience does not keep a readable copy, so nobody, including us, can show it to you again. If you lose it, delete it and create a new one.

Create a Token for Someone in Your Organisation (Org Scope)

Organisation admins can create a token for another person in their own organisation, for example a service account or a teammate who builds integrations.

curl -X POST "https://<your-sapience-address>/api/admin/mint-long-lived-token" \
  -H "Authorization: Bearer <your-sign-in-token>" \
  -H "Content-Type: application/json" \
  -d '{"username": "teammate", "number_of_months": 12, "name": "CRM sync"}'

The reply has the same shape as above, with the token carrying the teammate's permissions, not yours.

Rules to know:

The person must be in your organisation.

You can't create a token for someone with a higher role than yours.

If either rule fails, you get the same "forbidden" answer whether the username doesn't exist, belongs to another organisation, or outranks you. That is deliberate, so the endpoint can't be used to find out who has an account.

Regular users who try this get "forbidden". They can only create their own token.

Using Your Token

Send it with every request, in either of these ways:

Authorization: Bearer <your-token>

X-API-Key: <your-token>

It works like a normal sign-in for that account, until the expiry date.

See and Delete Tokens

List the tokens you can see:

curl "https://<your-sapience-address>/api/admin/long-lived-tokens" \
  -H "Authorization: Bearer <sign-in-token>"

You see your own active tokens. Organisation admins see every active token in their organisation. Each row shows an id, the label, who it was created for and by, when it expires, and the first characters of its fingerprint so you can match it to the one you saved. It never shows the token itself. Expired and deleted tokens are not listed.

Delete a token you no longer need, or one that may have leaked:

curl -X DELETE "https://<your-sapience-address>/api/admin/long-lived-tokens/<id>" \
  -H "Authorization: Bearer <sign-in-token>"

You can delete your own tokens. Organisation admins can also delete tokens belonging to people in their organisation. Once deleted, the token stops working.

Quick Reference

I want to…	Call	Who
Create a token for myself	`POST /api/admin/long-lived-tokens`	Anyone (3-month limit; org admins 24)
Create a token for a teammate	`POST /api/admin/mint-long-lived-token`	Org admins, own organisation
See tokens	`GET /api/admin/long-lived-tokens`	You: yours. Org admins: the whole organisation
Delete a token	`DELETE /api/admin/long-lived-tokens/<id>`	Owner, or their org admin

Keeping Tokens Safe

Treat a token like a password: keep it in a secrets manager or environment variable, never in code you share or commit.

Use the shortest lifetime that works, and give each script its own token with a clear name, so you can delete just that one if needed.

Every token creation and deletion is recorded.

Summary

Sign in, create a token for yourself (up to 3 months) or, as an organisation admin, for a teammate (up to 24 months), copy it once, and send it as Authorization: Bearer or X-API-Key. List your tokens to keep track of them and delete any you no longer need.