Skip to content

feat(apidocs): Publish org auth token endpoints - #130360

Merged
BYK merged 2 commits into
masterfrom
byk/feat/apidocs-publish-org-auth-tokens
Nov 7, 2026
Merged

BYK merged 2 commits into
masterfrom
byk/feat/apidocs-publish-org-auth-tokens

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

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/api client. 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".

Operation Endpoint operationId
GET /organizations/{org}/org-auth-tokens/ OrganizationAuthTokensEndpoint listOrganizationAuthTokens
POST /organizations/{org}/org-auth-tokens/ OrganizationAuthTokensEndpoint createOrganizationAuthToken
DELETE /organizations/{org}/org-auth-tokens/{token_id}/ OrganizationAuthTokenDetailsEndpoint deleteOrganizationAuthToken

GET and PUT on a single token stay PRIVATE. 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:tokens call 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:

  • Who can call it: a signed-in session, or an OAuth application token that holds org:tokens plus a scope_map scope (org:read/org:write/org:admin; DELETE needs org:write or org:admin).
    • Personal auth tokens, org auth tokens and integration tokens are always rejected with 403.
    • The schema's security block is derived from scope_map and can't express org:tokens or these rejections, so the descriptions state them.
  • List never returns a token's value, only tokenLastCharacters. It is not paginated.
  • Create:
    • Returns the full token exactly once.
    • Only org:ci can be granted, and org:tokens can never be granted.
    • An OAuth caller can only grant scopes its own token holds. Otherwise it gets 403 insufficient_scope.
    • Every new token is written to the audit log and emailed to all org owners.
    • Impersonated sessions are blocked by DisallowImpersonatedTokenCreation.
  • Delete deactivates the token (soft delete) and writes an audit log entry. A second call returns 404.
  • Both mutations set idempotent_methods = frozenset().

POST/DELETE: PUBLIC rather than PUBLIC_EXPERIMENTAL?

My view is that there's no strong reason against PUBLIC.

  • Publishing doesn't change who can call these endpoints. That's still enforced by the permission class, the org:tokens consent, the scope cap, owner emails and audit logs.
  • The request and response contract has been stable for more than two years.
  • The newest piece is the OAuth path from feat(auth): Allow OAuth tokens to manage org auth tokens #128051, which is about two weeks old. If its rules change, the likely changes are allowing more scopes or tightening the permission check. Neither changes the documented shape.
  • PUBLIC_EXPERIMENTAL would only make sense if Foundations expects to change the request body or the response, and I found nothing pointing that way.

Other changes

  • Response type: OrgAuthTokenSerializerResponse fields now have descriptions.
  • name stays optional in the request schema but its description says it's required. The serializer keeps required=False on 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.
  • Typed returns: return annotations use Response[T] arms, as flake8 S022 requires. The serializer errors path goes through as_validation_errors, with no runtime change.
  • Schema extension fix: apidocs/extensions.py now skips permission classes that have no scope_map. Without that, make build-api-docs crashed on DisallowImpersonatedTokenCreation. These are the first published endpoints to use that permission class.
  • Agent token permission matrix (test_organization_agent_token.py):
    • Adds an org auth token fixture for token_id and a POST payload.
    • These endpoints now assert that every token credential (personal, agent, scoped-down agent, approved agent and service account) is denied with 401/403.

Flag for Security: viewer context can call these endpoints

The matrix showed that a Seer-signed X-Viewer-Context request can list, create and revoke org auth tokens for the user. ViewerContextAuthentication (and the auth middleware) sets request.user without request.auth, so OrgAuthTokenPermission treats 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-docs and diffed openapi-derefed.json against master. The only changes are the three added operations above, plus the new OrgAuthToken, OrgAuthTokenCreate and OrgAuthTokenListResponse components. 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-docs and pnpm run validate-api-examples: pass
  • pytest tests/apidocs, test_organization_auth_tokens.py, test_organization_auth_token_details.py and tests/sentry/seer/endpoints/test_organization_agent_token.py: 545 passed, 23 xfailed
  • pytest tests/sentry/apidocs: 167 passed
  • prek run and mypy (--stage pre-push) on the changed files: pass

CODEOWNERS routes these files to app-backend, so I'm also requesting review from Foundations and Security.

via @BYK.

--

View Session [Sentry]

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
@sentry-junior
sentry-junior Bot requested review from a team as code owners November 7, 2026 16:05
@sentry-junior
sentry-junior Bot requested review from a team November 7, 2026 16:05
@github-actions github-actions Bot added the Scope: Backend Automatically applied to PRs that change backend components label Nov 7, 2026
@BYK
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
BYK merged commit ffc8a9b into master Nov 7, 2026
76 of 77 checks passed
@BYK
BYK deleted the byk/feat/apidocs-publish-org-auth-tokens branch November 7, 2026 16:36
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>
@linear-code

linear-code Bot commented Nov 13, 2026

Copy link
Copy Markdown

SEC-2168

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Scope: Backend Automatically applied to PRs that change backend components

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant