Authentication
Truework authenticates requests to our API using API keys. If an API key is not included with a request or the API key has been revoked, the request will return an error.
API keys can be used to create verification requests on your behalf, and to view the results of completed verifications. As such, they should be kept secret, and should not be checked into version control. If you suspect an API key has been published or compromised, you should revoke that API key and create a new one.
API key prefixes
Truework API keys begin with a mnemonic prefix to help you identify the purpose of a given key, and to avoid confusion between sandbox and production environments. The key prefixes are as follows:
Bearer tokens
The Truework API expects users to pass their API keys as bearer tokens (RFC 6750) to authenticate requests. The API key should be included in the Authorization header of the request, prefixed with the string “Bearer” and a space. For example, to correctly authenticate a request using the API key tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be, the HTTP request must contain the following header:
Creating an API key
To create an API key, navigate to your developer settings page.
Under the “API” header scroll down to the “Production” card, and expand the API key section by clicking the “Edit” button. Then, optionally enter a description for the key, and click “Generate”. The API key you created will appear in the card above. It will be a urlsafe string that begins with the prefix tw_sk_.
Revoking an API key
To revoke an API Key, simply click the “Revoke” button next to the key you wish to revoke. Make sure your key is not in use before revoking it as any request using the key will return errors once it is revoked. There is no way to undo this action.
Sandbox API keys
To create or revoke an API key for the sandbox environment, find the “Sandbox” card and follow the above instructions. Sandbox keys will have the prefix tw_sk_test_ to differentiate them from production keys.
How API keys are generated
API Keys are generated using Python’s built-in secrets library, which ensures cryptographic randomness of the produced bytes used in the API key. The number of bytes used in generating the API key is guaranteed to be at least 32 random bytes, though this number may increase without notice in the future.