API keys
| Environment | Prefix | Example |
|---|---|---|
| Sandbox | sk_test_ |
sk_test_i2fhPNWPG4cTmi1qCDVthAD7uTG6z6hf5lrHwddg |
| Live | sk_live_ |
sk_live_sFeAQm0nrtHEOkc483XcnWDSvOpNK7CZ0ptBI0ij |
A key is the prefix followed by 40 random letters and digits. The key decides the environment: a sandbox key sees only sandbox data, a live key only live data.
- Create keys in the panel under API keys → Create key. Choose the environment and give the key a name (for example, the service that uses it). Only the account owner and admins can manage keys.
- The full key is shown once, right after creation. We store only a hash; later the panel shows just the first characters so you can tell keys apart. If you lose a key, create a new one.
- Live keys can be created only after your business is verified — see Sandbox and live.
- You can have several active keys at once, for example one per service.
Never put a secret key in a browser, a mobile app, a WordPress theme or a public repository. Anyone with the key can create applicants and read document data in your account.
Sending the key
Send the key in the Authorization header of every request to https://kyc.goxost.net/api/v1:
curl https://kyc.goxost.net/api/v1/usage \
-H "Authorization: Bearer $KYC_SECRET_KEY"
$kyc = new GuzzleHttp\Client([
'base_uri' => 'https://kyc.goxost.net/api/v1/',
'headers' => ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')],
]);
$usage = json_decode($kyc->get('usage')->getBody(), true);
const usage = await fetch('https://kyc.goxost.net/api/v1/usage', {
headers: { Authorization: `Bearer ${process.env.KYC_SECRET_KEY}` },
}).then((r) => r.json());
usage = requests.get(
"https://kyc.goxost.net/api/v1/usage",
headers={"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"},
).json()
| Problem | Response |
|---|---|
| Missing, unknown or revoked key | 401 unauthenticated |
| Account blocked or not active | 403 forbidden |
| Live key, business not verified yet | 403 tenant_not_verified |
| ID belongs to another account or environment | 404 not_found |
The only endpoint that needs no key is the public document catalog, GET /documents/catalog.
Rotating and revoking keys
To rotate a key without downtime:
- Create a new key in the panel.
- Deploy it to your servers.
- Check that the old key is no longer used, then click Revoke next to it.
A revoked key stops working on the API immediately. The Direct API caches key checks briefly, so a revoked key may still be accepted there for up to 60 seconds. Revoke a key at once if it may have leaked, and create a new one.
Session tokens for the browser and app
The browser or mobile app never needs your secret key. When your backend creates a session (POST /applicants/{id}/sessions) it gets two values:
| Value | Use it for |
|---|---|
url |
The hosted flow: redirect the user, send the link, or show it as a QR code |
token |
The SDKs: pass it to kyc.js or the Flutter SDK |
Both belong to one session of one applicant and expire with it (60–1800 seconds, 30 minutes by default). They cannot call /api/v1 and cannot see other applicants. The SDKs send the token as Authorization: Session <token> to the verification service themselves — you do not need to call those endpoints directly.
The result the SDK reports in the browser or app is for the user experience only. Take the final decision on your backend from the webhook or GET /verifications/{id}.
Idempotency keys
Network errors happen. To retry a write request safely, send an Idempotency-Key header with POST, PATCH and DELETE requests:
curl https://kyc.goxost.net/api/v1/applicants \
-H "Authorization: Bearer $KYC_SECRET_KEY" \
-H "Idempotency-Key: 3f1c9a7e-2b4d-4e8a-9c61-5d0f7b2a8e14" \
-H "Content-Type: application/json" \
-d '{"external_id": "user-8812"}'
- The key is 8–64 characters from
A–Z a–z 0–9 _ -. A UUID works well. A wrong format returns400 bad_request. - For 24 hours, the same key with the same request returns the saved response with the header
Idempotent-Replayed: true. Nothing is created twice. - The same key with a different body returns
409 idempotency_conflict. - If the first request with this key is still running, you get
409 conflict— wait and retry. 5xxresponses are not saved, so a retry after a server error runs the request again.- Keys are scoped to your API key. Use a new key for each new operation.
Rate limits
Each API key can make 600 requests per minute. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. Above the limit you get 429 rate_limited with a Retry-After header (seconds). Some endpoints have extra limits — see Errors.