How to give an AI agent integration an API key that can only do one thing
Create one organization key per integration and grant only the scope it needs. Confirm the integration's call works with that key alone. When the integration ends, or the key leaks, revoke that one key and confirm the same call is refused.
The usual failure is not a missing feature. It is one powerful key shared by five integrations. A reporting script ends up able to write, and a single leak exposes everything. Scoped keys fix that only if you use them one integration at a time.
The pattern
| Integration | Key name | Scope it needs | What it must NOT be able to do |
|---|---|---|---|
| Nightly agent report | report-nightly | read the org's agents | write anything |
| Ticket bridge | tickets-bridge | the one agent it talks to | reach other agents |
| Internal admin tool | admin-console | org-wide | (trusted, and the only one) |
Our API keys documentation describes the scope types and expiry options available when you create a key.
Step by step
1. Create the key for one integration. Name it after the integration, not after a person.
report-nightly still makes sense after the person who set it up leaves. dana-key does not.
2. Grant the narrowest scope. For a read-only report that lists agents, that is a read scope on agents and nothing else.
3. Check the listing, not just the create response. The key should appear by name with its scopes and as enabled, and the listing should not show the secret value.
4. Prove the key works for its one job:
curl -s -o /dev/null -w "%{http_code}\n" \
"https://api.agent.ceo/api/v1/customers/$ORG/agents" \
-H "X-API-Key: $REPORT_KEY"
# expect 200
5. Prove the known-negative. The same call with a key you made up must be refused:
# INVENTED_KEY: any string you made up, never issued by agent.ceo
curl -s -o /dev/null -w "%{http_code}\n" \
"https://api.agent.ceo/api/v1/customers/$ORG/agents" \
-H "X-API-Key: $INVENTED_KEY"
# expect a 4xx refusal
6. Revoke and prove it. Revoke report-nightly, rerun step 4 and require a refusal where you
used to get 200.
Rendering diagram…
Why steps 5 and 6 matter
Step 5 proves your test can fail. Step 6 proves revocation is real. Without step 5, a broken endpoint that refuses everyone would look like a successful revocation in step 6.
More on how agent.ceo scopes keys: Platform API keys.
FAQ
How do I give an AI agent integration a least-privilege API key?
Create a separate organization key for that one integration, grant only the scope it needs (for example read access to the organization's agents), confirm that the call the integration makes succeeds with that key alone, and keep the key's name so it can be revoked on its own later. One key per integration means one revocation per incident.
Can I see an API key's secret value again after creating it?
You should not be able to. A key listing should show the key's name, scopes and whether it is enabled, but not the secret value. If a list of keys returns the secrets themselves, anyone who can read that list holds every key.
How do I test that revoking an API key actually worked?
Make the same call that succeeded before revocation and require a refusal. Also run the call with a key you invented. A test that passes for a live key and a fabricated key alike is not testing revocation.