HTTP API overview
The Zyton API is JSON over HTTPS at https://api.zyton.ai. At launch it records, checks and revokes consent grants for your end users, keeps your audit trail and verifies signed consent tokens and certificates. The API reference lists every endpoint, and the TypeScript SDK does all of this for you.
- Version prefix:
/api/v1 - Authentication: exchange your secret API key for an access token at
POST /oauth/token, then send that token asAuthorization: Bearer. Never send the key itself: every API refuses it. - Access tokens last 5 minutes. A revoked or rotated key stops working within 5 minutes, when the last token it was exchanged for expires.
- Sandbox keys (
pip_sk_test_…) and live keys (pip_sk_live_…) call the same host. Consent grants are kept per environment: a sandbox key never sees, checks or revokes a live grant.
Get an access token
Send grant_type=client_credentials with your key, either with HTTP Basic (the key as the user name, no password) or as client_secret in a JSON or form body. Reuse the token until it expires (expires_in is in seconds) or a call answers 401, then get a new one.
curl -s https://api.zyton.ai/oauth/token -u "$PIP_API_KEY:" -d grant_type=client_credentials
# {"access_token":"eyJhbGciOiJFUzI1NiIs…","token_type":"Bearer","expires_in":300}What a key can't do
A key is for the API only. Key tokens get 403 on billing and on GDPR data subject request (DSAR) routes, and they can't manage keys, passwords, MFA or sessions. A person signed in to this portal does those.
Error responses
Every API answers an error with JSON: a readable error and a stable code (AUTH_…, CONSENT_…, AUDIT_… or VERIFY_…). Build on the code; the text can change.
{
"error": "Consent grant not found",
"code": "CONSENT_GRANT_NOT_FOUND"
}| HTTP | Code | Meaning |
|---|---|---|
| 400 | CONSENT_INVALID_SCOPE / CONSENT_INVALID_VALIDITY / AUTH_OAUTH_INVALID_REQUEST | A field, the body or a query parameter is invalid, or a field isn't known. The error says which. |
| 401 | AUTH_OAUTH_INVALID_CLIENT | From POST /oauth/token: the key is wrong, revoked or rotated. |
| 401 | CONSENT_UNAUTHORIZED | The access token is missing, invalid or expired. Get a new one and retry. |
| 403 | CONSENT_FORBIDDEN / CONSENT_API_KEY_FORBIDDEN | The token can't call this route: it isn't an API-key token, or the route needs a person signed in (DSAR routes answer CONSENT_API_KEY_FORBIDDEN). |
| 404 | CONSENT_GRANT_NOT_FOUND | No such grant in your organisation and key environment. A grant of another organisation gets the same answer. |
| 429 | AUTH_RATE_LIMITED | Too many failed key attempts from your IP address: 30 in 15 minutes block key exchanges from it for 15 minutes. |
| 500 | CONSENT_DATABASE_ERROR / CONSENT_INTERNAL_ERROR | Something failed on our side. Retry with backoff, and contact support if it keeps happening. |
Limits
There are no per-key request quotas or rate-limit headers yet. The exception is the token endpoint: after 30 failed attempts from one IP address in 15 minutes it answers 429 for 15 minutes. Reuse access tokens instead of exchanging the key for every request; the SDK does.
Need help? Contact support with the time of the request, the endpoint and the error code.