Authentication
API keys, test and live environments, the two accepted headers, short-lived tokens and key safety.
API keys#
Every request to the API carries an API key. You create keys in the developer portal under API keys.
| Prefix | Environment | What it does |
|---|---|---|
tv_test_sk_ | Test (sandbox) | Returns demo data only. Available on every account. |
tv_live_sk_ | Live | Runs real checks and counts against your plan. Needs a paid plan. |
Sending the key#
Send the key in the Authorization header as a bearer token:
HTTP
Authorization: Bearer tv_test_sk_...Or, if your HTTP client makes that awkward, in the X-TrustVerify-API-Key header. If you send both, Authorization wins.
HTTP
X-TrustVerify-API-Key: tv_test_sk_...curl -sS -X GET 'https://api.trustverify.co.uk/api/v1/validate-key' \
-H "Authorization: Bearer $TRUSTVERIFY_API_KEY"Short-lived tokens#
If you would rather not send the long-lived key on every call, exchange it for a short-lived access token with POST /api/v1/token and send the token as the bearer value until it expires.
Errors#
| Status | When |
|---|---|
| 401 | The key is missing, malformed, revoked or expired. |
| 403 | The key is valid but not allowed: its IP allow-list does not include the caller, the account email is not verified, or the account is not approved. |
| 429 | The key is over its rate limit or its plan's monthly quota. See Rate limits. |
| 503 | The key is valid but its plan could not be read. Nothing was processed. Retry shortly. |
Keeping keys safe#
- Call the API from your server only. Never put a key in a browser, a mobile app or a public repository.
- Use one key per system so you can revoke one without stopping the others.
- Restrict live keys to your servers' IP addresses in the portal.
- If a key leaks, revoke it in the portal straight away and create a new one.