CONNECT AN API
Connect an API¶
Connecting an API gives your agent a named set of operations on one outside service, with the credential held in your Enclave's vault on your own machine.
This page is for whoever is wiring the first one up.
Every API works the same way, so you learn it once: connect it, grant one capability, and every call comes back with a signed receipt. The per-service pages below only cover what differs, which is the credential and where to get it.
The credential you paste never reaches EKKA. A connection is per machine, because the credential lives on the machine and does not leave it.
What can I connect?¶
Ask your own installation rather than trusting this list to be current:
| API | What it is | Connect |
|---|---|---|
| Gmail | Your own mailbox. List, read and send. | ekka api connect gmail |
| Gmail, shared mailbox | A company mailbox that outlives whoever set it up. | ekka api connect gmail-org |
| Slack | Slack Web API. Post and read messages. | ekka api connect slack |
| Amazon S3 | One S3 bucket. List, read, write and delete objects. | ekka api connect s3 |
| Sentry | Read issues and error events, change an issue's status. | ekka api connect sentry |
| Jira | Jira Cloud. Read issues, comments, projects and transitions from one site. | ekka api 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.
What are the five steps?¶
Every connection is the same five commands. Only step 3 differs per API.
1. See what it is.
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.
It asks for the credential with the input hidden, stores it in the vault, and writes the connection.
The credential is read from a prompt
connect takes it from a prompt, or from --stdin in a script. It is never
a command-line argument, so it never appears in shell history or in the
process list.
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.
What does test tell me?¶
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.
How do I write 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:
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.
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.