Skip to main content

Authentication

API Keys​

The Warrant API uses API Keys to authenticate requests. You can view and manage your API keys in the Warrant Dashboard.

Requests made to the Warrant API using one of the official Warrant SDKs will correctly authenticate requests provided the SDK is initialized correctly. To make an authenticated request to the Warrant API directly (without an SDK), set the API key in the Authorization header, prefixing the value with ApiKey .

Authenticated API Request
curl "https://api.warrant.dev/v2/object-types" \
  -H "Authorization: ApiKey api_prod_f5dsKVeYnVSLHGje44zAygqgqXiLJBICbFzCiAg1E="

There are two types of API keys: Application Keys and Admin Keys.

Application Keys​

Application keys are the API keys your application(s) should use to make requests to the Warrant API. This includes actions like creating object-types/warrants/objects, checking if a user has access to a resource, and more. Application keys are scoped to an environment (e.g. prod, test, etc) and are prefixed with api and the environment identifier (e.g. prod) to make it easy to identify the key and which environment it is scoped to. Requests made with one environment's application key cannot access the data in another environment.

An example of an application key is shown below:

api_prod_f5dsKVeYnVSLHGje44zAygqgqXiLJBICbFzCiAg1E=

Create an Application Key​

Application keys are automatically created when an environment is created. Currently, application keys cannot be revoked or rolled. If you would like to revoke a compromised application key, contact us.

Revoke an Application Key​

Currently, application keys cannot be revoked by customers. If you would like to revoke a compromised application key, contact us.

Roll an Application Key​

Currently, application keys cannot be rolled by customers. If you would like to roll an application key, contact us.

Admin Keys​

Admin keys can be used to manage organization-level resources like environments. This includes creating a new environment, updating an existing environment, and deleting an existing environment. They are global across your organization, meaning they are not scoped to any one environment. Admin keys are prefixed with org to indicate that they are organization-level keys. They are typically used in scripts and tools for testing, workflow automation, and Continuous Integration (CI) and cannot be used by your application to manage authorization.

An example of an admin key is shown below:

org_key_2bpHNBkoJvykfOLYd5sSSOSpt8q

Create an Admin Key​

To create a new admin key, click on Create Key in the Admin Keys section of the Account > API keys tab of the Warrant Dashboard. Follow the steps to generate a new key. Once the key is generated, copy it and store it somewhere safe (like a password/secrets manager) as the value will not be displayed again.

Revoke an Admin Key​

To revoke an admin key, click the delete (trash can) icon for the key you want to revoke from the Admin Keys section of the Account > API keys tab of the Warrant Dashboard. Once you confirm the action, the key will be revoked immediately, and any API requests made using the key will fail. This action cannot be undone.

Roll an Admin Key​

To roll an admin key, click on the refresh icon for the key you want to roll. Choose an expiration time for the existing key: the options are now, 1 hour, and 1 day. If you choose now, the existing key will be revoked immediately and any API requests made using the key will fail. If you choose an expiration time of 1 hour or 1 day, the existing key will continue to work until the selected expiration time has passed. Regardless of the selected expiration time, a new key will be created for use immediately. Once the new key is generated, copy its value and store it somewhere safe (like a password/secrets manager) as it will not be displayed again.

Errors​

Requests made to the Warrant API without an API key or with an invalid API key will be returned a 401 Unauthorized response. To learn more about the errors returned by the Warrant API, refer to the section on Errors.

Session Tokens​

Warrant supports the use of short-lived session tokens to make check requests scoped for a user. Session tokens can be created through the Warrant API. For applications using an external identity provider, such as Auth0 or Firebase, you can also use the ID tokens generated by the identity provider in place of a session token. To learn more, refer to Creating Client Sessions.