Use secret keys on your server and publishable keys in web pages.
| Key | Looks like | Use it | It can |
|---|---|---|---|
| Secret key | kyc_live_... | On your server only | Create, read and cancel your sessions, as its scopes allow |
| Sandbox key | kyc_sandbox_... | On your server, in development and CI | The same, for simulated sessions only. See Sandbox |
| Publishable key | pk_live_... | In web pages, with a verify button | Start a verification from one of your buttons, and nothing else |
link Secret keys
Send your secret key in the Authorization header of every API request, as a bearer token:
curl https://www.kaywhysee.com/api/v1/sessions/$SESSION_ID \
-H "Authorization: Bearer kyc_live_..."Create keys in the dashboard under Developers → API keys. Only your organisation's admins can create and revoke them. You can have several, each with its own name, so a key for each service or environment is easy to retire on its own. A key belongs to the workspace it was created in: the verifications it starts land there, and applicants see that workspace's name.
Keep secret keys secret
A secret key is shown once, when you create it, and we only keep a hash of it. Never put it in a web page, a mobile app or a code repository. If one leaks, revoke it straight away: it stops working at once.
link Scopes
Each secret key has scopes: the calls it may make. Give a key only what its system needs. A reporting job that reads results, for example, needs sessions:read and nothing else.
| Scope | Allows |
|---|---|
sessions:create | Create a session |
sessions:read | Retrieve a session |
sessions:cancel | Cancel a session |
sessions:read_data | The details read from the document, with Retrieve a session |
You choose a key's scopes when you create it; all four are ticked to start with. Keys created before sessions:read_data existed don't have it. To change them, create a new key and revoke the old one. A call outside a key's scopes gets a 403:
{
"success": false,
"data": null,
"error": {
"code": "AUTHORIZATION_ERROR",
"message": "This API key doesn't have the sessions:create scope. Use a key that does, or create one in Developers > API keys."
}
}link Rotating a key
- Create a new key and deploy it to your servers.
- Check the old key's Last used time in the dashboard stops moving.
- Revoke the old key.
link Publishable keys
Each account has one publishable key, used by verify buttons. It's safe in a web page because all it can do is start a verification from one of your buttons, and you can limit which websites may use each button. You'll find it on Developers → Verify buttons, where you can also rotate it.
link When authentication fails
Requests without a valid secret key get a 401:
{
"success": false,
"data": null,
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "That API key is not valid."
}
}A key also stops working if your account is suspended. A valid key used for a call outside its scopes gets a 403 instead, so you can tell the two apart.