API keys
API keys are how your application authenticates with Toden. You create and manage them in the console. This page is for the developer who sets up an integration and for whoever is responsible for keeping its credentials safe. For how to send a key with a request, see Authentication.
Where to find it
Open Developers → API Keys at console.toden.co. The environment selector in the console header decides which keys you see and which kind you create: Sandbox or Production. Keys from one environment never appear in the other.
Key types and prefixes
A publishable key starts verifications from a client. A secret key does everything a publishable key can, and also reads full results, personal data and captured media. A publishable key that calls a secret-only endpoint gets 403 secret_key_required.
A key works only in its own environment. Sending a Sandbox key to Production, or the reverse, returns 403 environment_mismatch.
Create a key
A secret key is shown once, when it is created. Toden stores only a hash of it, so nobody, including Toden support, can show it to you again. If you lose it, create a new key and revoke the old one.
What you can see afterwards
A publishable key is safe to ship in client code, but it can still start billable verifications. That is why read-only roles do not see it in full.
The list also shows each key’s name, type, status (Active or Revoked), who created it, when it was created and when it was last used.
Production keys need an approved business
Creating a pk_live_ or sk_live_ key requires that Toden has approved your business profile. Until then the Production option is locked in the console, and the request returns 403 business_not_approved. Sandbox keys are available from the start. See Go live.
Restrict a key
Restrictions limit where a key can be used, so a copied key is useless elsewhere. They are optional: a key with an empty list is unrestricted. Open a key’s actions and choose Restrict key (or Edit restrictions once some are set).
The kind of restriction depends on the key type.
Each list holds up to 20 entries. Duplicates are removed.
Publishable: web origins
Secret: IP ranges
Enter each origin as scheme and host, with a port if it is not the default: https://app.example.com. Paths are ignored, and only http and https are accepted.
- A browser request whose
Origin(or, failing that,Referer) is not on the list is refused. - A request with no origin at all is allowed. Native mobile SDKs and server callers send no
Origin, so an origin list does not affect them.
This is a browser control. It stops a key lifted from your site being used on another site. It does not stop a non-browser client, which can omit the header. For a backend, use a secret key restricted by IP.
Add restrictions in Sandbox first and confirm your integration still works. A wrong IP range on a live secret key stops your backend from reading results until you correct it.
Revoke a key
Choose Revoke key from the key’s actions. Revocation is immediate and permanent: the next request made with that key returns 401 with Invalid API key. A revoked key stays in the list, marked Revoked, so the history remains readable. It cannot be re-enabled.
Rotate a key safely
There is no in-place rotation. Rotating a key means replacing it.
Create the replacement
Create a new key of the same type in the same environment. Apply the same restrictions.
Deploy it
Update your secrets manager or client configuration, and release. For a publishable key in a mobile app, wait until the versions carrying the old key are no longer in use.
If a secret key may have been exposed, reverse the order: revoke it first, then deploy the replacement. A short outage is better than a leaked key that can read personal data.
What is recorded
Creating a key, revoking a key and changing restrictions are written to the audit log as api_key.created, api_key.revoked and api_key.restrictions_updated. The entry holds the key name, type, environment and prefix, never the key itself. Toden also sends the api_key.created and api_key.revoked webhook events.