API Key Permissions

How to scope API keys and validate permissions behavior.

View as Markdown

Why this matters

API keys can now be constrained by permission flags and ownership scope. This lets you issue least-privilege keys for automation instead of sharing a full-access tenant key.

Permission-aware key creation

Create scoped keys with explicit permissions:

curl -X POST https://api.agentry.to/agent/v0/api-keys \
  -H "Authorization: Bearer ag_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-only monitor",
    "permissions": {
      "read_inbox": true,
      "read_api_key": true
    }
  }'

You can also create keys on scoped resources:

  • POST /agent/v0/inboxes/{inbox_id}/api-keys
  • POST /agent/v0/pods/{pod_id}/api-keys

Verify persistence and readback

After creating a key, list keys and confirm permission fields round-trip correctly:

curl -X GET https://api.agentry.to/agent/v0/api-keys \
  -H "Authorization: Bearer ag_your_admin_key"

Check that each api_keys[] entry includes the expected permissions object and scope fields (inbox_id or pod_id where applicable).

Operational guidance

  • Rotate keys regularly and avoid sharing keys between services.
  • Keep high-privilege keys in secure secret stores only.
  • Prefer separate keys per workload so revocation is low-risk.