Token Management
A token acts as your system's identity credential: it tells Trustpair who is making the request and what they are allowed to do. Each token carries a specific set of permissions, scoped exactly to the modules and actions your integration needs.
Tokens are sensitive credentials. A token must be treated like a password. It should never be shared openly, stored in plain text, or visible in logs, emails, or code repositories. Access to a token should be restricted to the people and systems that strictly need it.
1. How to Create a Token
Only workspace admins can create API tokens. Bearer tokens are created and managed exclusively from the Trustpair web app — they cannot be generated programmatically.
Step 1️⃣ — Open the Token Management page
From the Trustpair web app, go to Administration → API Tokens. You will see a list of all existing tokens and their current status.
Step 2️⃣ — Click "Create API Token"
A creation form will appear.
Step 3️⃣ — Name your token
Give the token a clear, descriptive name so you can identify its purpose later (e.g. SAP-Production, Kyriba-Connector). Avoid generic names like test or 1234.
Step 4️⃣ — Select permissions
Choose exactly which permissions to grant. Each permission can be set to read-only, read/write, or not granted at all. Only select what the integration actually needs — granting excess permissions increases risk if the token is ever compromised.
The permissions available to you depend on your Trustpair subscription. If a module is not visible, it is not included in your plan.
For a full breakdown of what each permission covers, see the Permission Reference section below.
Step 5️⃣ — Set an expiry date (optional)
Choose when the token should expire: 30, 90 or 180 days, 1 year, a custom date, or Never (default: 90 days). Setting an expiry date is recommended — a token that rotates regularly is far less dangerous if it ever leaks.
The expiry date cannot be changed after creation. To move it, rotate the token (see bellow).
Step 6️⃣ — Save and copy your token immediately
Once you click Save, your token value is displayed once and only once. Copy it immediately and store it securely (e.g. in a secrets manager or a secure vault). Then click Close.
After you close this screen, the full token value can never be retrieved again — not by you, and not by Trustpair support. If you lose it, you will need to revoke the token and create a new one.
2. How to Manage Your Tokens
Viewing token details
Click the ⋯ menu on any token in the list and select Show details to review its name, permissions, and current status. The full token value is never shown again — only the last few characters are visible for identification purposes.
Rotating a token
Rotation replaces a token’s secret without changing its name or permissions, and lets the old secret keep working for a short grace period — so you can switch your integration to the new secret with no downtime. Use it to refresh a secret regularly, or to replace one before it expires.
Like creation, rotation is a manual action in the web app — it cannot be triggered through the API or machine-to-machine.
How to rotate:
- Click the ⋯ menu next to the token
- Select Rotate
- Choose how long the current token stays active: Revoke immediately, 24 hours, 7 days (default) or 30 days
- Choose the new token’s expiry (same options as creation)
- Click Rotate, then copy the new secret immediately — it is shown once and only once, exactly like at creation
During the grace period, both the old and new secrets work. The old token shows as “Rotated — expires [date]” in the list and stops working when the grace period ends. Deploy the new secret to your integration before then.
Revoke immediatly“Revoke immediately” ends the old secret at once, with no overlap. Only choose it if the new secret is already in place, or if the current one is compromised and must be cut off now — otherwise your integration will fail until the new secret is deployed.
Expiry reminderTrustpair automatically sends an email and in-app notification 7 days before a token expires, to the workspace managers of the account the token belongs to. It's a reminder to rotate the token in time and avoid any interruption to your integration.
Revoking a token
If a token is compromised, no longer in use, or needs its permissions updated, revoke it immediately.
How to revoke:
- Click the ⋯ menu next to the token
- Select Revoke
The token is instantly deactivated and can no longer be used to call the API. Revoked tokens remain visible in the list for audit purposes, but they cannot be reactivated.
Tokens cannot be edited. To change the permissions on a token, create a new token with the correct permissions and revoke the old one. To renew the secret while keeping the same permissions, rotate the token instead.
Permission reference
| Permission | What read access allows | What write access allows |
|---|---|---|
| Company Account Check (M1 — Control) | View vendor verification records | Create and update vendor verification records |
| Company Account Audit (M2 — Audit) | View vendor pairs and their audit data | Create and update vendor pairs |
| Payment Check (M3 — Payment) | View payment verification results | Create and submit payment checks |
| Cases | View cases and their details | Create cases, add comments, submit and manage overrides |
| Users | List workspace users | — |
| Documents | Download documents | Upload documents |
| Document Analysis | View AI analysis results on documents | Trigger an AI analysis on an uploaded document |
| Paid Payment | View payment history | — |
| Tags | View and List tags | Create and manage tags |
The required permissions for each API endpoint are documented in the API Reference.
Updated 4 days ago