CONNECT AN API

Connect an API¶

Your agent reaches third-party services through APIs you connect. The credential you paste stays in your Enclave's encrypted vault, on your own machine. EKKA never receives it.

Every API works the same way, so learn it once. The pages below only cover what is different about each one: which credential it needs, and where to get it.

What you can connect¶

Ask your own installation rather than trusting this list to be current:

ekka api list

API	What it is	Credential	Guide
`slack`	Slack Web API. Post and read messages.	A bot token (`xoxb-`)	Connect Slack
`s3`	One Amazon S3 bucket.	An access key pair	`ekka api describe s3`
`sentry`	Sentry. Read issues and error events, change an issue's status.	An internal-integration token	Connect Sentry
`jira`	Jira Cloud. Read issues, comments, projects and transitions from one site.	A service-account API token	Connect Jira

More arrive without you upgrading anything. An API is a row in our catalog, not a release, so ekka api list can grow between versions of the CLI.

Not on the list? Your internal services are not ours to describe, so you add them to the catalog yourself and they stay private to your organization. See Add your own API.

The five steps, once¶

Every connection is the same five commands. Only step 3 differs per API.

1. See what it is.

ekka api describe slack

Its address, the credential it wants, how EKKA checks that credential still works, and every operation a plan can name.

2. Get the credential. This is the only part that happens outside EKKA, and it is what each guide below covers.

3. Hand it to your Enclave.

ekka api connect slack

It asks for the credential with the input hidden, stores it in the vault, and writes the connection.

Never put a credential on the command line

connect prompts for it. Anything you type as an argument lands in your shell history and in the process list, where other users on the machine can read it.

4. Let an agent use it. connect prints this command with your values already filled in:

ekka gate grant add --type api --instance <your-api-gate> \
  --resource apis/slack --capability api.read --no-fingerprint

api.read lets the agent read. Add a second grant with api.write when you want it to make changes too. Until you run this, nothing can call the API, which is the point: connecting and permitting are two decisions.

5. Check it actually works.

ekka api test slack

What `test` tells you¶

Four separate answers, because the four things that break have four different fixes:

  ok       config      https://slack.com · bearer
  ok       credential  API_CREDENTIAL_SLACK is in the vault
  ok       grant       govern allows api.read on apis/slack
  ok       live call   GET /api/auth.test answered as expected

The verdict printed under the rows reads WORKING only when all four of them passed. A check that could not be performed says so and the command still exits non-zero, so a green row always means something was verified.

The last check is a real call to the API. That matters more than it looks: Slack answers a dead token with a success response whose body says {"ok": false}, so a check that read only the response code would report a broken connection as healthy.

Writing a plan against it¶

Name the operation. No URLs, no HTTP methods:

{ "id": "post", "action_ref": "ekka.gate.api.v1",
  "target": "<your api gate>", "op": "send", "call": "postMessage",
  "inputs": { "resource": "apis/slack",
              "channel": "#ops", "text": "@input.message" } }

To see every operation and the inputs it takes, in the shape a plan wants them:

ekka api spec slack

Common questions¶

Does EKKA ever see my credential?

No. It goes from your keyboard into your Enclave's encrypted vault and stays on that machine. Govern authorizes the action and signs the receipt without the credential ever crossing it, which is why a receipt can prove what your agent did without anyone having to trust us with the key.

Why do I create the Slack app myself instead of clicking install?

So the credential is yours. A one-click install would hand the token to the publisher of the app. Creating it in your own workspace keeps the token on your machine, which is the guarantee everything else here is built on.

Can two machines share one connection?

No. The credential lives in one machine's vault and never leaves it, so each machine connects for itself. Nothing is copied between them, so losing one machine cannot expose another.

What happens when I revoke a grant?

The next call is refused. The connection and the credential stay where they are, so restoring access is a new grant rather than setting the whole thing up again.

Two things worth knowing¶

A connection belongs to one machine. The credential is in that machine's vault and never leaves it, so an API connected on your laptop is not connected on a colleague's. Each machine connects for itself.

Removing one is one command.

ekka api disconnect slack

That deletes the connection, its documentation and the credential from this machine. The catalog entry is untouched, so you can connect it again whenever you want.