Auth Tokens

Learn about the different kinds of Auth Tokens Sentry provides, and when to use which.

Auth tokens (short for authentication tokens) are a way to authenticate with Sentry. They are similar to passwords but are designed for programmatic interaction with Sentry. Some examples of what you would use auth tokens for include:

  • Uploading Source Maps during your CI build
  • Using Sentry CLI to interact with Sentry
  • Using the Sentry API

Each auth token is created with a certain set of permissions and scopes which are mapped to the Sentry API's Permissions & Scopes. Some types of auth tokens have set permissions that can't be edited, while others can be customized upon token creation and edited later.

We recommend using a separate auth token for each use case. For example, you would use a different auth token to upload source maps than the one you use with Sentry CLI. This has the benefit that if an auth token is compromised, you can revoke that auth token without impacting the rest of your workflow.

There are three key types of auth tokens in Sentry:

  • Organization Auth Tokens: These tokens are bound to an organization, and have access to all projects within that organization. They have a limited set of permissions and are designed to be used in CI environments and with Sentry CLI.

  • Internal Integrations: These tokens are bound to an organization, and have access to all projects within that organization. They can be created with a custom set of permissions, and are designed to be used in cases where organization auth tokens don't have sufficient access rights.

  • User Auth Tokens: These tokens are bound to a user, and have access to all organizations and projects that user has access to.

For most scenarios, we recommend using Organization Auth Tokens. They are designed to be used in CI environments and have a limited set of permissions. This means that if the place you stored the auth token is compromised, the attacker can only do limited damage.

Organization auth tokens permissions aren't customizable. They are set to allow most CI-related tasks, without any unnecessary permissions.

Internal Integrations should be used when you need full API access (which the organization auth tokens cannot grant), and you want to interact with the Sentry API on behalf of an organization. For example, to programmatically create a new project, you would use an internal integration.

Permissions for auth tokens created as part of an internal integration are customizable and editable.

User Auth Tokens should be used to interact with the Sentry API on behalf of a user. For example, to fetch all issues for a user, you would use a user auth token. We don't recommend using user auth tokens for CI tasks because if the user who created the token is removed from the Organization, the token will stop working.

User auth token permissions are customizable but cannot be edited later.

Organization auth tokens can be created in sentry.io on the Auth Tokens page under Settings > Developer Settings > Auth Tokens.

They can also be generated on certain pages of Sentry's docs if you're signed in, and by using the Sentry Wizard to configure uploading source maps.

Organization auth token names are generated for you unless you create the token through the Sentry UI. This name is only used for display purposes - it helps to identify an auth token in case you want to revoke it later. You can change the name for an organization auth token at sentry.io on the Edit Auth Token page under Settings > Developer Settings > Auth Tokens.

For security reasons, organization auth tokens are only visible once, right after you create them. If you lose the auth token, you will have to create a new one. This means you can't see the full token on the overview page or on the token detail page, you can only see the last characters of the token to help identify it.

Any user can create organization auth tokens for any of their organizations. This allows any user (not only organization owners) to configure a Sentry SDK and set up CI processes by creating and using organization auth tokens. Since organization auth tokens have limited access, there is limited potential for abuse.

All owners of the organization will receive a security email when a new organization auth token is created and can revoke these tokens at any point. Only organization owners & managers can revoke organization auth tokens .

We recommend only using an internal integration when you want to interact with the Sentry API on behalf of an organization. See Sentry's API Authentication docs for more information on how to do this.

To get started, see our docs on Internal Integrations.

User auth tokens can be created in sentry.io on the User Auth Tokens page under the Account dropdown in the top left.

User auth tokens can be created by any user, and are bound to that user. The tokens can be given permissions to all organizations and projects that user has access to. This means a user auth token's maximum scope is all the scopes that the user has access to for a given organization. A user auth token cannot exceed the permissions of the user who created it. See Organization and User Management for more details on how permissions work in Sentry.

When you create a new user auth token, you can select which scopes the token should have in the UI:

Currently, you can view user auth tokens in the UI after creating them. This is a legacy behavior that may change in the future. We recommend only using each user auth token once, and creating a new token for each use case. Any user can always revoke any of their user auth tokens.

We recommend only using a user auth token to interact with the Sentry API on behalf of a user. See Sentry's API Authentication docs for more information on how to do this.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").