Authentication
Every request carries an API key in the Authorization header. No other header, query parameter or cookie is read.
Authorization: Bearer tna_api_Q7vK2mXeR4w…The key#
| Format | a long random token that starts with tna_api_. Store it whole and treat it as opaque |
| Issued by | your MASK administrator, on the API Keys page. The key is shown once; if it is lost, the administrator replaces it |
| Prefix | the first 16 characters (tna_api_Q7vK2mXe) are not secret: they name the key on the API Keys page. Quote the prefix, never the key, when you talk to the administrator |
| Rotation | the administrator replaces the secret, and the old one stops working on the next request, with no grace period. Plan a rotation as: receive the new key, deploy it, done |
| Revocation | permanent and immediate. Every other change the administrator makes (scopes, institutions, IP allowlist, rate limit, expiry) also applies on the next request |
| Expiry | optional; GET /integration/key shows expiresAt when there is one |
The key works only under /api/v1/integration/. A key sent anywhere else is refused, and the web app's sign-in tokens are refused on the integration routes.
Authentication errors#
| Case | HTTP | code |
message |
|---|---|---|---|
No Authorization header, another scheme, or a key that is not valid (an old secret after a rotation included) |
401 | invalid_api_key |
Invalid API key |
| The key was revoked | 401 | key_revoked |
The API key has been revoked |
| The key has expired | 401 | key_expired |
The API key has expired |
| The key has an IP allowlist and the request comes from another address | 403 | ip_not_allowed |
This address is not allowed to use the API key |
A 401 carries WWW-Authenticate: Bearer realm="mask-integration".
curl -s "$MASK/integration/key"{
"status": "error",
"code": "invalid_api_key",
"message": "Invalid API key",
"requestId": "163a283e-df84-4f6f-8be0-c7ab57ecf1cb"
}Keeping the key safe#
Keep the key in a secret store: never in a URL, a log, a ticket or source control. Use HTTPS only. If a key may have leaked, ask the administrator to rotate it; the old secret stops at once. More in Network and key safety.