Sentry first-install setup

Use one Public App approval to connect Sentry for read-only issue investigation and issue events. This guide covers the project Connections workflow, installation and project-selection APIs, and scoped agent tools. Connecting does not install the issue-triage managed template or configure runtime Sentry telemetry.

​

Operator prerequisites

The platform operator configures the public App and the server, rather than asking customers to create an App or copy its credentials: The server also needs its existing envelope-encryption key. App credentials and that key do not belong in tenant request bodies or sessions. Issue webhooks use the central shared intake endpoint, not a tenant-specific webhook URL. Missing or inconsistent configuration fails closed. A local Verify Install flag or redirect setting does not prove that the corresponding remote App setting is correct: initial authorization requires a fresh installation readback with status pending. Reusing an existing local connection uses project selection instead of replaying first-install authorization. Deploy migration 0300_sentry_connection_discovery before using organization and region discovery; a source merge does not apply it.

​

Set up in the web interface

In the initiating project’s Connections page, use the ordinary Sentry row. Connection setup and project selection require an active organization administrator. The current auto project supplies the destination; changing accounts or projects does not transfer an attempt. There is no separate Sentry settings page.

​

Disconnect and reconnect

Use the row’s Disconnect action and its confirmation dialog to remove Sentry access from this auto project. It clears this project’s allocations and disables its subscriptions across the row’s connected grants, without revoking the shared organization grant, remotely uninstalling the App, or disconnecting other auto projects. The row returns to Not connected. Connect again to reuse the existing installation and choose projects from its recorded provider visibility. Newly created Sentry projects are not automatically authorized. Unchanged selected subscriptions keep their identity; disconnecting and recreating a subscription cannot authorize old queued deliveries.

​

Browser callback and pending work

HTML callbacks return HTTP 303 with Cache-Control: no-store and Referrer-Policy: no-referrer to the initiating project’s Connections page. Pending work uses ?sentryAttempt={attemptId}; completed, registered setup uses ?connectionOAuth=success&provider=sentry. Neither return URL contains authorization codes, state or installation credentials. Caller-supplied redirect destinations are ignored. Malformed or unauthorized callbacks return to the fixed, query-free /connections/sentry/error page. Old /{organizationSlug}/{projectSlug}/connections/sentry bookmarks redirect to Connections; a valid legacy attempt UUID becomes sentryAttempt. Reopening a callback that is no longer awaiting authorization does not exchange its code again. Connect can resume the initiating administrator’s unexpired awaiting_selection, exchanging or completing attempt. While an attempt is exchanging, completing or has an uncertain confirmation response, the open modal polls status every two seconds without overlapping reads or replaying mutations. Closing it stops those reads. Browser setup API requests time out after two minutes; timeout does not prove that a provider operation was undone. Failed or expired operations need operator reconciliation, not replay, reinstall or uninstall as a workaround.

​

Existing MCP-only connections

Existing MCP-only grants keep their identities, project allocations and original OAuth path. They are not silently converted into Public App grants. If sentry is already taken, the default first-install name becomes sentry- plus the attempt UUID’s first eight characters. Reference the resulting connection name, not an assumed name. An old MCP token does not authorize Public App installation; the new connection requires its own App approval. Copying another tenant’s installation ID does not establish consent.

​

CLI workflow

Run auto connect sentry --allow <project> to use the same connection flow. Without --allow, the active project is used; a project must be selected. The connection-start response can be connected with a provider and message, or authorization_required with the consent or project-selection URL. Sentry replacement requests return not_implemented guidance rather than replacing the shared installation. During authorization waiting, the CLI recognizes an existing grant becoming connected to the project through sentryConnection.connected; a new grant ID is not required. A listed but unconnected Sentry grant does not count as success. For an installation-backed grant, auto allow sentry <project> --connection <name> allocates all projects in its recorded visibility. Use the chooser or project-selection API when you need a narrower selection. Use the web row’s project-scoped Disconnect rather than treating organization-wide connection removal as equivalent.

​

Authenticated setup sequence

The caller must be an authenticated, active organization administrator with provider_grants:write and provider_grants:use access in the initiating project. An agent or service-account principal cannot substitute for that user. Start checks that all intended destinations are active projects in the same organization; selection and publication recheck administrator authority for the selected recipients. All paths below are relative to /api/v1/connections/sentry/installations. The {attemptId} path value is the setup attempt’s UUID, not the provider installation UUID.

​

1. Start an attempt

The POST body requires organizationId and projectId; the remaining fields are optional. Unknown fields are rejected: Use the returned authorizationUrl for provider consent. The server generates a random state, stores its hash, and binds it to the initiating user, organization, project, intended destinations, and App. The attempt expires after 15 minutes; submitting a different user or tenant coordinate does not transfer its ownership.

​

2. Complete the provider callback

The callback accepts a 43-character base64url-shaped state, an installationId UUID, and a nonempty printable-ASCII code of at most 8,192 characters. It authenticates against the attempt’s persisted scope and requires the same initiating user; state alone is not user authorization. Before the single exchange, the server claims the authorization-code hash, not ownership of the supplied installation UUID. Only successful exchange and exact App, installation, organization, region, scope, and project-visibility readback establish the installation claim. An invalid code therefore does not reserve another tenant’s installation UUID. Concurrent or replayed callbacks cannot repeat the exchange. Successful proof normally advances the attempt to awaiting_selection, exposing verified project IDs and slugs before publication. If exactly one Sentry project and one destination are available, the callback proceeds through confirmation and publication automatically. At least one visible project is required. Enumeration is bounded to ten pages of at most 100 projects; incomplete, repeated, malformed, or oversized enumeration is rejected rather than used as partial permission. Provider pagination URLs are not followed.

​

3. Select recipients and publish

Send a PUT body containing only recipients, an array of 1–100 objects. Each object contains only projectId and sentryProjectId. The destination ID must be one of the intended projects; the Sentry project ID must be a positive decimal string from the verified visible projects. Duplicate destination/Sentry-project pairs are collapsed. Provider visibility is read again before confirmation and after the installation is marked installed using its installation token. A short database transaction then rechecks the initiating user’s authority, recipient membership, expiration, installation identity, and uninstall records. It atomically publishes one installation, one scoped grant, the selected project allocations/subscriptions, and central credential generation 1. Tokens are not copied into leaf grants; private attempt ciphertext is cleared on completion. One initial consent can select multiple Sentry projects and multiple permitted destination projects through the API; the browser chooser uses only the current destination. The organization grant records verified project visibility, while each destination’s allocation and subscriptions independently constrain investigation and intake. Completion emits connection-established lifecycle events. This is not independent authorization for another tenant. Existing outbound MCP connections are unchanged.

​

Manage selected projects through the API

GET /api/v1/connections/sentry/projects?organizationId={organizationId}&projectId={projectId} returns the administrator’s installation-backed connection options. Each option contains id, name, organizationSlug, projects (verified IDs and slugs), selectedProjectIds for this auto project, and available. Availability reflects a recorded ready or refreshing installation credential, not a successful live tool call. PUT /api/v1/connections/sentry/projects accepts only organizationId, projectId, providerGrantId and sentryProjectIds. The first three are nonempty strings; the last is an array of at most 100 positive decimal ID strings from recorded visibility. Duplicate IDs are collapsed. Both endpoints require an authenticated organization administrator and provider_grants:write plus provider_grants:use in that project. A nonempty selection updates this project’s allocation and subscriptions. An empty array disconnects this project without remote uninstall. Unchanged subscriptions are retained; removed subscriptions are disabled with a new generation, and reconnect creates new subscription identities. The update records an audit entry and emits connection-established or connection-removed lifecycle events. Other projects’ allocations remain unchanged.

​

Read-only agent tools

Reference the Public App connection with kind: connection, provider: sentry and its actual connection name. The installation-backed surface contains four tools; an agent’s exact-name tool allowlist can narrow it further. The server checks live project authorization before issue metadata and latest-event reads, and again before releasing their buffered diagnostics. Issue details use regional REST reads, not hosted detail enrichment. The event must match the verified stable issue and project; a missing latest event returns event: null. Output includes projected issue metadata and event-owned exception, stacktrace, thread, message, request and breadcrumb entries. Distributed trace, span, conversation and release enrichment is omitted. This is not a general secret-redaction guarantee. Only issue search uses the hosted MCP path, fixed to the selected organization and project. Arbitrary catalog execution, mutation tools and other upstream tools are not exposed. Rejected allowlist calls stop before credential lookup or provider I/O. Discovery metadata alone does not establish live access. Installation-backed requests resolve a server-held shared credential, refreshing near expiry through the installation’s single-owner refresh path. Tokens are not copied into the sandbox or leaf grants. Concurrent callers do not independently rotate that token, and uncertain refresh outcomes remain unavailable rather than authorizing another rotation. Existing MCP-only grants continue through their original OAuth resolver.

​

Interpret status without implying activation

Status includes the attempt ID, expiry, initiating scope, intended destinations, Sentry organization and region, project choices, and a nullable providerGrantId. Organization and region can be null before discovery. Project choices are returned only for an unexpired awaiting_selection attempt. Setup JSON responses use Cache-Control: no-store and Referrer-Policy: no-referrer; authentication and deployment-policy failures use their existing response handlers. Status does not return App secrets, authorization codes, state hashes, or token ciphertext. Do not infer live delivery from completed or registered, or use the unsupported Sentry trigger test-fire path as activation proof.

​

Cancellation and uncertain outcomes

Cancel an unfinished attempt with the installation API’s DELETE. Cancellation clears its pending credential locally and never remotely uninstalls the shared App. Dismissing the browser modal is not this API operation. A completed attempt cannot be canceled through this route; use the row’s project-scoped Disconnect or the project-selection API for that project. Organization-grant revocation remains a separate, broader action described in shared intake. Code-hash claims and provider-proven installation claims are not released by failure, cancellation, or elapsed time. Unknown exchange or confirmation outcomes are not automatically retried or recovered. If a process stops in exchanging or completing, expiry does not authorize another exchange, token rotation, or subscriber. Provider HTTP happens outside database locks. A cancellation, permission change, uninstall, lost confirmation response, or failed local publication can leave a remotely confirmed installation without a local grant. Report that uncertain outcome for separately authorized operator reconciliation; local rollback does not undo remote effects, and this API does not compensate with remote uninstall. Malformed requests or invalid selections return HTTP 400; setup authorization failures return 403, unknown attempts 404, invalid state or unavailable installation claims 409, and unavailable operator setup 503. Read the current attempt status and the specific error rather than retrying a possibly consumed callback or widening its recipient scope.