Skip to content

Commit

Permalink
fix(docs): Match user token update and prioritize internal integratio…
Browse files Browse the repository at this point in the history
…ns (#7918)

### Background
As part of the change to [Introduce Scope Hierarchy](https://www.notion.so/sentry/24Q3-Permission-Scope-Hierarchy-67620f99783345bbb8bc2828b1addc64), I edited the page where you create user auth tokens to use the same dropdowns as internal integrations in getsentry/sentry#54651. You can test this for yourself [here](https://sentry.io/settings/account/api/auth-tokens/new-token/).

### Changes
1. Clarify that user auth tokens are not editable after they are created. In order to change the scopes on them, you must create a new token.
2. Replace old picture of the create user auth page from box selectors to the new dropdowns
3. I moved user auth tokens to below integration tokens to hopefully have people favor integration > user tokens. In the future, we will probably look into eventually deprecating user auth tokens in favor of the other 2 tokens.
4. For the internal integration, I changed the wording from 
`See our docs on Internal Integrations to learn more.`
to
`To get started, see our docs on Internal Integrations`
because it wasn't immediately clear to me which link in that section leads to the steps to create the integration.
  • Loading branch information
schew2381 committed Sep 21, 2023
1 parent d8d60b1 commit 1586111
Show file tree
Hide file tree
Showing 4 changed files with 15 additions and 15 deletions.
Binary file removed src/api/auth-token.png
Binary file not shown.
4 changes: 2 additions & 2 deletions src/api/permissions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ different API endpoints.

To set the scopes for an [integration token](/product/integrations/integration-platform/#permissions), select the scopes from the dropdown. These can be edited later.

To set the scopes for an auth token, check the necessary boxes when [creating an auth token](https://sentry.io/api/).
To set the scopes for an auth token, select the scopes from the dropdown when [creating an auth token](https://sentry.io/api/). These cannot be edited later.

![](auth-token.png)
![](../docs/product/accounts/auth-tokens/user-auth-token-create.png)

If you're looking for information on membership roles please visit the
[membership](/product/accounts/membership/) documentation.
Expand Down
26 changes: 13 additions & 13 deletions src/docs/product/accounts/auth-tokens/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,26 +21,26 @@ There are three key types of auth tokens in Sentry:
- [Organization Auth Tokens](#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.

- [User Auth Tokens](#user-auth-tokens):
These tokens are bound to a user, and have access to all organizations and projects that user has access to.

- [Internal Integrations](#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](#user-auth-tokens):
These tokens are bound to a user, and have access to all organizations and projects that user has access to.

### When Should I Use Which?

For most scenarios, we recommend using [Organization Auth Tokens](#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.

[User Auth Tokens](#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 and editable.

[Internal Integrations](#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](#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

[Organization auth tokens](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) can be created in [sentry.io](https://sentry.io) on the **Auth Tokens** page under **Settings > Developer Settings > Auth Tokens**.
Expand All @@ -59,6 +59,12 @@ Any user can create organization auth tokens for any of their organizations. Thi

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 .

### Internal Integrations

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](/api/auth/) docs for more information on how to do this.

To get started, see our docs on [Internal Integrations](/product/integrations/integration-platform/).

### User Auth Tokens

[User auth tokens](https://sentry.io/settings/account/api/auth-tokens/) can be created in [sentry.io](https://sentry.io) on the **User Auth Tokens** page under the Account dropdown in the top left.
Expand All @@ -76,9 +82,3 @@ Currently, you can view user auth tokens in the UI after creating them. This is
![](user-auth-tokens-overview.png)

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

### Internal Integrations

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](/api/auth/) docs for more information on how to do this.

See our docs on [Internal Integrations](/product/integrations/integration-platform/) to learn more.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

1 comment on commit 1586111

@vercel
Copy link

@vercel vercel bot commented on 1586111 Sep 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

sentry-docs – ./

sentry-docs-git-master.sentry.dev
docs.sentry.io
sentry-docs.sentry.dev

Please sign in to comment.