Authentication and API Key management

How Truework Authenticates API requests

Truework authenticates requests to our API using API Keys and Publishable Keys. If the required authentication token is not included with a request or is revoked, the request will return an error.

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.

An API Key is used to create verification requests, view the results of completed reports, cancel a verification request, and create internal API dashboards. API Keys should be kept secret, and should not be checked into version control. If you suspect an API key has been compromised, you should revoke that API key and immediately create a new one.

For those using the Truework Direct order endpoint, a Publishable Key is also required. A Publishable Key is used to initialize the Truework.js widget and support co-branding. This key type is not meant to be secret. This means you can safely include the Publishable Key in public facing code, like Javascript/HTML.

API and Publishable Key management

Creating an API key

To create an API key:

1. Navigate to developer settings in the Truework app
2. Under the “API” header scroll down to the “Sandbox” or “Production” card, depending on the environment you are generating the key for, and expand the API Key section by clicking the “Edit” button.
3. Optionally, enter a description for the key, and click “Generate”.

The API key you created will appear in the card as a urlsafe string that begins with the prefix tw_sk_test_ in Sandbox tw_sk_ in Production.

Creating a Publishable key

To create a Publishable key:

1. Navigate to developer settings in the Truework app
2. Under the “Publishable Key” header scroll down to the “Sandbox” or “Production”card, depending on the environment you are generating the key for, and expand the Publishable Key section by clicking the “Edit” button.
3. Optionally enter a description for the key, and click “Generate”.

The API key you created will appear in the card above.

Revoking an API or Publishable Key

To revoke an API or Publishable 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 and there’s no way to undo this action.

Have questions?

Not a problem. Email us at implementations@truework.com.