Skip to content
API reference Get API keys

Integration · Chapter 4

Authentication

Your backend authenticates with a secret API key; the user's browser or app only gets a short-lived session token.

3 min read

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.
Important

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:

  1. Create a new key in the panel.
  2. Deploy it to your servers.
  3. 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.

Note

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 returns 400 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.
  • 5xx responses 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.