---
title: API Key Permissions
description: How to scope API keys and validate permissions behavior.
surface: shared
---

## 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:

```bash
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:

```bash
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.