Repository navigation
feat(apidocs): Publish org auth token endpoints - #130360
Merged
Merged
Conversation
Mark listing, creating and revoking org auth tokens PUBLIC and document them, so the Sentry CLI can manage CI tokens through the generated @sentry/api client. GET and PUT on a single token stay private. The schema's security block is derived from scope_map, which can't express the extra `org:tokens` requirement or the rejection of personal, org auth and integration tokens, so the descriptions spell that out with the one-time token value, the owner emails and the audit log. Create and revoke are declared non-idempotent. The security scheme extension now skips permission classes without a scope_map, such as DisallowImpersonatedTokenCreation, which these are the first published endpoints to use. The agent token permission matrix gains an org auth token fixture and expects every token credential to be denied on these endpoints. Refs #130351
BYK
approved these changes
Nov 7, 2026
BYK
enabled auto-merge (squash)
November 7, 2026 16:08
…blish-org-auth-tokens # Conflicts: # tests/sentry/seer/endpoints/test_organization_agent_token.py
BYK
added a commit
to getsentry/toolkit
that referenced
this pull request
Nov 7, 2026
… revision operations (#2093) Next batch of moving the CLI onto `@sentry/api` generated operations (follows #2073, #2075, #2078, #2090). `@sentry/api` 1.49.0 publishes three endpoints the CLI already calls: | CLI function | Endpoint | Operation | Published by | | --- | --- | --- | --- | | `listTraceLogs` (`log list --trace`, `trace logs`) | `GET /organizations/{org}/trace-logs/` | `listOrganizationTraceLogs` | getsentry/sentry#130357 | | `listDashboardRevisionsPaginated` (`dashboard revisions`) | `GET /organizations/{org}/dashboards/{id}/revisions/` | `listOrganizationDashboardRevisions` | getsentry/sentry#130358 | | `restoreDashboardRevision` (`dashboard restore`) | `POST /organizations/{org}/dashboards/{id}/revisions/{rev}/restore/` | `restoreOrganizationDashboardRevision` | getsentry/sentry#130358 | These calls stop using `apiRequestToRegion` and behave the same as before: - The CLI's valibot schemas still validate each response, so schema mismatches still fail as "Unexpected response format". - Region routing goes through `getOrgSdkConfig`. - Pagination still uses the Link-header cursors, including the previous cursor for revisions. - 401/403 errors are still enriched by `unwrapResult`. - On the wire, `traceId` and `sort` are sent as single repeated params, the same as before. - The dashboard and revision ids are passed as strings with the same cast `getDashboard` uses. The SDK URL-encodes them the way the old code did. All three operations have `experimental: false`. Bumping to 1.49.0 also pulls in the 1.47.0 regen and 1.48.0's `experimental` flag. Typecheck and generated docs don't change. ### Still on the helpers | Call site | Endpoint | Waiting on | | --- | --- | --- | | `issues.ts` `getSharedIssue` (raw fetch) | `GET /shared/issues/{share_id}/` | getsentry/sentry#130359 merged after the 1.49.0 regen, so it needs the next release | | `releases.ts` set-commits | `GET /organizations/{org}/releases/{version}/previous-with-commits/` | same as above (#130359) | | `org-auth-tokens.ts` (3 sites) | list/create/delete `/organizations/{org}/org-auth-tokens/` | getsentry/sentry#130360 (auto-merging) | | `projects.ts` dsn-lookup | `GET /organizations/{org}/dsn-lookup/` | getsentry/sentry#130367 | | `auth.ts` | `GET /api/0/` (control silo) | getsentry/sentry#130369 | | `users.ts` | `GET /auth/` → `GET /users/me/` | getsentry/sentry#130368 | | `organizations.ts` | `GET /users/me/regions/` | #2091 replaces it with `listOrganizations` | | `traces.ts` / `logs.ts` | `GET /projects/{org}/{project}/trace-items/{id}/` | sentry publish PR still to come | | `preprod-artifacts.ts` | build assemble, snapshot archive status and trigger, snapshot create (zstd body) | sentry publish PRs still to come | | `projects.ts` | `GET /projects/?query=dsn:` fallback for old self-hosted servers | not public; needs a decision (see below) | These are the agreed exceptions: `trials.ts` (`/customers/*` and the product-trial PUT), snapshot `upload-options` and archive `?download`, `downloadBuildArtifact`'s install URL, chunk-upload server URLs, and `rawApiRequest` for `sentry api`. **Needs a decision:** the self-hosted DSN fallback from #2090 calls `GET /projects/?query=dsn:`, which isn't in the public schema. It needs to be added to the exception list for the lint rule, or dropped once old self-hosted versions age out. ### Testing - `pnpm run tsc` and `pnpm run lint` pass. - `pnpm run test` fails only on the 5 file-permission tests that also fail on `main` in the sandbox (`completions` ×2, `upgrade`, `db/resilient`, `dsn/code-scanner`), plus `@sentry/cli3to4`, whose codemod binary needs GLIBC 2.35. - Added unit tests for the revision list (cursors, schema rejection) and for restore (operation args, error naming). The trace-logs test now checks `traceId` and `sort` on the wire. <!-- junior-request-attribution:start --> via @BYK. <!-- junior-request-attribution:end --> <!-- junior-session-footer:start --> <!-- junior-conversation-id:agent%3A80220b9d4c297e2a971f05dcb03af515 --> -- [View Session](https://junior-prod.sentry.dev/conversations/agent%3A80220b9d4c297e2a971f05dcb03af515) [[Sentry]](https://sentry.sentry.io/explore/conversations/agent%3A80220b9d4c297e2a971f05dcb03af515/?project=4510944073809921) <!-- junior-session-footer:end --> Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: BYK <126780+BYK@users.noreply.github.com>
BYK
pushed a commit
to getsentry/toolkit
that referenced
this pull request
Nov 7, 2026
…-release and shared-issue operations (#2095) Next batch of moving the CLI onto `@sentry/api` generated operations. Stacked on #2093 (1.49.0). It gets retargeted to `main` once #2093 merges. `@sentry/api` 1.50.0 publishes five endpoints the CLI already calls: | CLI function | Endpoint | Operation | Published by | | --- | --- | --- | --- | | `listOrgAuthTokens` (`token list`) | `GET /organizations/{org}/org-auth-tokens/` | `listOrganizationAuthTokens` | getsentry/sentry#130360 | | `createOrgAuthToken` (`token create`) | `POST /organizations/{org}/org-auth-tokens/` | `createOrganizationAuthToken` | getsentry/sentry#130360 | | `deleteOrgAuthToken` (`token delete`) | `DELETE /organizations/{org}/org-auth-tokens/{id}/` | `deleteOrganizationAuthToken` | getsentry/sentry#130360 | | `getPreviousReleaseCommit` (`release set-commits`) | `GET /organizations/{org}/releases/{version}/previous-with-commits/` | `getOrganizationPreviousReleaseWithCommits` | getsentry/sentry#130359 | | `getSharedIssue` (share links in `issue view`), raw `customFetch` until now | `GET /organizations/{org}/shared/issues/{share_id}/` | `getOrganizationSharedIssue` | getsentry/sentry#130359 | All five operations have `experimental: false`. Behavior is unchanged: - **Org auth tokens** still go to the control silo, and `OrgAuthTokenSchema` still validates the responses. 401/403 errors are still enriched by `unwrapResult`. The token id goes into the path as-is, with the same `as unknown as number` cast as the other numeric-string ids. - **Previous release** routes by org through `getOrgSdkConfig`. The SDK encodes the version, and the silent fallback to `undefined` stays. - **Shared issue** calls the operation with `customFetch` rather than the authenticated transport, because a share URL's host may not be the logged-in one and must never get a bearer token. Custom headers stay URL-scoped (`applyCustomHeaders`). The CLI's "TLS certificate error", "Share link not found or expired", "Failed to resolve share link", "Share link returned invalid JSON" and missing-issue-ID errors are the same as before. The bump regenerates `plugins/sentry-cli/skills/sentry-cli/references/event.md`, which reorders the event fields from the schema regen. No fields were added or removed. ### Still on the helpers | Call site | Endpoint | Waiting on | | --- | --- | --- | | `preprod-artifacts.ts` | build assemble, snapshot archive status and start, snapshot create (zstd body) | shipped in 1.51.0 (getsentry/sentry#130371). The next stacked branch, `ref/cli-sentry-api-1.51`, is ready | | `projects.ts` dsn-lookup | `GET /organizations/{org}/dsn-lookup/` | getsentry/sentry#130367 | | `auth.ts` | `GET /api/0/` (control silo) | getsentry/sentry#130369 | | `users.ts` | `GET /auth/` → `GET /users/me/` | getsentry/sentry#130368 | | `organizations.ts` | `GET /users/me/regions/` | #2091 replaces it with `listOrganizations` | | `traces.ts` / `logs.ts` | `GET /projects/{org}/{project}/trace-items/{id}/` | sentry publish PR still to come | | `replays.ts` replay list | `GET /organizations/{org}/replays/` | `replay list --json` prints `info_ids`/`warning_ids`, which the generated `field` enum leaves out. Needs a sentry docs fix or a decision | | `projects.ts` | `GET /projects/?query=dsn:` fallback for old self-hosted servers | not public; needs a decision (see #2093) | These are the agreed exceptions: `trials.ts` (`/customers/*` and the product-trial PUT), snapshot `upload-options` and archive `?download`, `downloadBuildArtifact`'s install URL, chunk-upload server URLs, and `rawApiRequest` for `sentry api`. ### Testing - `pnpm run tsc` and `pnpm run lint` pass. - `pnpm run test` fails only on the 5 file-permission tests that also fail on `main` in the sandbox (`completions` ×2, `upgrade`, `db/resilient`, `dsn/code-scanner`), plus `@sentry/cli3to4`, whose codemod binary needs GLIBC 2.35. - The org-auth-token tests now go through the mocked SDK fetch and check the control-silo URL, method, body and error naming. The existing shared-issue tests (404, TLS, invalid JSON, missing id, header scoping) pass unchanged. <!-- junior-request-attribution:start --> via @BYK. <!-- junior-request-attribution:end --> <!-- junior-session-footer:start --> <!-- junior-conversation-id:agent%3A80220b9d4c297e2a971f05dcb03af515 --> -- [View Session](https://junior-prod.sentry.dev/conversations/agent%3A80220b9d4c297e2a971f05dcb03af515) [[Sentry]](https://sentry.sentry.io/explore/conversations/agent%3A80220b9d4c297e2a971f05dcb03af515/?project=4510944073809921) <!-- junior-session-footer:end --> Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Publishes the org auth token operations the Sentry CLI uses to manage CI tokens, so they reach the public OpenAPI schema and the generated
@sentry/apiclient. Refs #130351, where these endpoints were proposed for publishing. In the Slack discussion that led to it, the request was that org auth tokens "should be public too unless you have strong opposition".GET /organizations/{org}/org-auth-tokens/OrganizationAuthTokensEndpointlistOrganizationAuthTokensPOST /organizations/{org}/org-auth-tokens/OrganizationAuthTokensEndpointcreateOrganizationAuthTokenDELETE /organizations/{org}/org-auth-tokens/{token_id}/OrganizationAuthTokenDetailsEndpointdeleteOrganizationAuthTokenGETandPUTon a single token stayPRIVATE. The CLI doesn't use them, and the issue didn't ask for them.Why now: the endpoints have existed since 2023-06-20, and their request and response shapes haven't changed since. #128051 (2026-10-23) let OAuth application tokens holding
org:tokenscall them. That is the path the CLI needs, so publishing them now gives the CLI a typed, documented client.Security-relevant behavior, now in the operation descriptions
These come from
OrgAuthTokenPermission(src/sentry/api/bases/organization.py) and the endpoint code:org:tokensplus ascope_mapscope (org:read/org:write/org:admin;DELETEneedsorg:writeororg:admin).securityblock is derived fromscope_mapand can't expressorg:tokensor these rejections, so the descriptions state them.tokenLastCharacters. It is not paginated.tokenexactly once.org:cican be granted, andorg:tokenscan never be granted.insufficient_scope.DisallowImpersonatedTokenCreation.idempotent_methods = frozenset().POST/DELETE: PUBLIC rather than PUBLIC_EXPERIMENTAL?
My view is that there's no strong reason against
PUBLIC.org:tokensconsent, the scope cap, owner emails and audit logs.PUBLIC_EXPERIMENTALwould only make sense if Foundations expects to change the request body or the response, and I found nothing pointing that way.Other changes
OrgAuthTokenSerializerResponsefields now have descriptions.namestays optional in the request schema but its description says it's required. The serializer keepsrequired=Falseon purpose, so the endpoint can return its existing{"detail": "The name cannot be blank."}error, which tests assert. Making it required in the schema would change that error body.Response[T]arms, as flake8 S022 requires. The serializer errors path goes throughas_validation_errors, with no runtime change.apidocs/extensions.pynow skips permission classes that have noscope_map. Without that,make build-api-docscrashed onDisallowImpersonatedTokenCreation. These are the first published endpoints to use that permission class.test_organization_agent_token.py):token_idand a POST payload.Flag for Security: viewer context can call these endpoints
The matrix showed that a Seer-signed
X-Viewer-Contextrequest can list, create and revoke org auth tokens for the user.ViewerContextAuthentication(and the auth middleware) setsrequest.userwithoutrequest.auth, soOrgAuthTokenPermissiontreats it like a session. This is how master behaves today and this PR doesn't change it; the matrix just records it. Please confirm it's intended, or say if it should be denied in a follow-up.Schema check
I ran
make build-api-docsand diffedopenapi-derefed.jsonagainst master. The only changes are the three added operations above, plus the newOrgAuthToken,OrgAuthTokenCreateandOrgAuthTokenListResponsecomponents. The "(Optional) Shows the difference between the prod and dev schema" check is expected to fail on a schema-changing PR.Tests run locally
make build-api-docsandpnpm run validate-api-examples: passpytest tests/apidocs,test_organization_auth_tokens.py,test_organization_auth_token_details.pyandtests/sentry/seer/endpoints/test_organization_agent_token.py: 545 passed, 23 xfailedpytest tests/sentry/apidocs: 167 passedprek runand mypy (--stage pre-push) on the changed files: passCODEOWNERS routes these files to app-backend, so I'm also requesting review from Foundations and Security.
via @BYK.
--
View Session [Sentry]