CONNECT AN API · SENTRY · 5 MINUTES

Connect Sentry¶

Sentry needs an auth token, and the kind matters more than anything else on this page. The token goes straight into your Enclave's vault and never reaches EKKA.

You need the Manager or Owner role in your Sentry organization. Sentry's "Admin" role sits below Manager and cannot do this.

What you'll have at the end

A token in your Enclave's vault, a connection pinned to one Sentry organization, and a grant that says which agent may use it.

Step 1 · Create the token¶

Sentry offers three kinds of token, and two of them will not work, so this is the first thing to get right.

Kind	Where	Works?
Internal Integration	Settings → Developer Settings	Yes. Use this.
Organization Auth Token	Settings → Auth Tokens	No. Locked to `org:ci`.
Personal Token	User Settings → Auth Tokens	Works, but dies with your account.

An Organization Auth Token sounds like the right answer and is not. Sentry fixes its scopes at org:ci, which covers source map upload, release creation and code mappings, for every customer on every Sentry plan. There is no setting to change. It cannot read a single issue, and it answers {"detail":"Invalid org token"} to everything EKKA needs.

An Internal Integration is the one you want: it belongs to the organization rather than to a person, it does not expire, you choose its permissions, and you can revoke it from the same page.

Open Settings → Developer Settings → Custom Integrations
Click Create New Integration, choose Internal
Name it something you will recognize later, e.g. EKKA Enclave
Leave the webhook URL empty. EKKA only reads; webhooks are Sentry pushing to you, which is not what this connection is for

Set these permissions and leave everything else at No Access:

Permission	Level	What it buys
Issues & Events	Read	listIssues, getIssue, listIssueEvents
Project	Read	listProjects
Organization	Read	reading the organization itself
Issues & Events	Write	only if plans should resolve or archive issues

Click Save. The token appears on the integration's page

Start at Read

Adding Issues & Events = Write later is one click. A plan that can close a customer's bug ticket is a decision worth making on purpose rather than by default.

If the button is grayed out

Sentry says "Manager or Owner permissions are required to create a new integration". Its role order, highest first, is Owner → Manager → Admin → Member → Billing. Admin is third, not second. Ask an Owner to create the integration, or to raise your role.

Step 2 · Find your region and organization slug¶

Both are answered once, when you connect.

Region is us or de. Find it under Settings → General Settings → Data Storage Location. This is not a latency preference: a Sentry organization stored in the EU cannot be reached through the US host at all. They are separate installations that share a brand, so the wrong answer fails outright.

Organization slug is the name in your Sentry URL, not the display name. If you are at sentry.io/organizations/acme-corp/issues/, your slug is acme-corp.

Step 3 · Connect¶

ekka api connect sentry --input organization=acme-corp --input region=us

It asks for the token on a hidden prompt. The token never appears in your shell history or in the process list, and it goes into your machine's vault, not into EKKA.

The connection is named after the organization:

✓ connection written, pinned to sentry@2

  Grant your agent the right to use it:
    ekka gate grant add --type api --instance <your api gate> \
      --resource apis/sentry-acme-corp --capability api.read --no-fingerprint

Why the organization is asked twice

The slug sits inside the URL path, so a plan step has to supply it. Answering it here as well pins the connection: the Enclave refuses any call naming a different organization, before the request is sent.

This matters because one token often sees several organizations. Without the pin, a single grant would reach all of them and a one-character slip in a plan would read the wrong company's errors. With it, apis/sentry-acme-corp can only ever reach acme-corp.

Have two Sentry organizations? Connect twice. Each gets its own name and its own grant.

Step 4 · Grant¶

Run the command connect printed. Add a second one with --capability api.write only if you gave the integration Issues & Events = Write and want plans to change issue status.

Step 5 · Use it in a plan¶

ekka api spec sentry

prints the step for every operation. A read looks like this:

{
  "action_ref": "ekka.gate.api.v1",
  "target": "<your Enclave's api gate>",
  "op": "read",
  "call": "listIssues",
  "inputs": {
    "resource": "apis/sentry-acme-corp",
    "organization": "acme-corp",
    "query": "is:unresolved",
    "project": "mobile-app",
    "statsPeriod": "24h",
    "limit": "25"
  }
}

resource names the connection. organization must match the one it is pinned to. Everything else is a filter.

What you can call¶

Call	What it does	Needs
`listIssues`	Issues, newest first. Filter by `project` (a slug), `environment`, `query`, `statsPeriod`, `limit`.	Issues & Events = Read
`getIssue`	One issue's detail.	Issues & Events = Read
`listIssueEvents`	The error events inside one issue. `full: "true"` adds the stack trace, which is large.	Issues & Events = Read
`listProjects`	The projects in the organization.	Project = Read
`updateIssue`	Set status to `resolved`, `unresolved` or `ignored`. `ignored` is what the UI calls Archive.	Issues & Events = Write

Filter by project

Most organizations have several projects. project takes a slug, the name you see in Sentry such as mobile-app, and it accepts a comma-separated list. Without it a plan fetches every project and throws most of it away against the response cap.

When something is wrong¶

Every call answers {"detail":"Invalid org token"}. You used an Organization Auth Token. See Step 1 and create an Internal Integration instead.

Every issue call is refused. The token is valid and the integration lacks Issues & Events = Read. Scopes are the real boundary, not the catalog: EKKA describes what Sentry offers, and the token decides what actually happens.

Reads work and updateIssue is refused. The integration has Read but not Write for Issues & Events.

Nothing is found, whatever you ask for. Check the region. A de organization is unreachable through the US host, and the reverse.

API_RULE_DENIED, "the request was refused before it was sent". The plan named a different organization from the one this connection is pinned to. That is the pin doing its job. Check organization in the step, or connect a second time for the other organization.

Proving a Sentry connection

Run a plan against it. A listIssues step like the one above returns the issues the token can see and leaves a receipt for the call.

Self-hosted Sentry¶

This entry is for sentry.io. A self-hosted Sentry lives on your own host, so it needs its own catalog entry. That is a row you add yourself, not a change to EKKA. See Add your own API.