> ## Documentation Index
> Fetch the complete documentation index at: https://agentmail.manicule.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://agentmail.manicule.dev/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://agentmail.manicule.dev/api/mcp.
> Every agent surface: https://agentmail.manicule.dev/.well-known/llms-manifest.json

# Create API Key (/api-reference/create-api-key-3)

<!-- agent-signals: reading_time_min: 11 · est_tokens: 7762 · updated: 2026-09-29 -->
Related: [Sign Up](/api-reference/sign-up.md), [Attach Human](/api-reference/attach-human.md), [Verify](/api-reference/verify.md), [List Inboxes](/api-reference/list-inboxes.md), [Create Inbox](/api-reference/create-inbox.md), [Search Inboxes](/api-reference/search-inboxes.md)

# Create API Key

`POST /v0/pods/{pod_id}/api-keys`

> **CLI:**
> ```bash
> agentmail pods api-keys create --pod-id <pod_id> --name "My Key"
> ```

Base URL: `https://api.agentmail.to`

Base URL: `https://x402.api.agentmail.to`

Base URL: `https://mpp.api.agentmail.to`

Base URL: `https://api.agentmail.eu`

## OpenAPI

```json
{
  "servers": [
    {
      "url": "https://api.agentmail.to",
      "description": "prod"
    },
    {
      "url": "https://x402.api.agentmail.to",
      "description": "prod-x402"
    },
    {
      "url": "https://mpp.api.agentmail.to",
      "description": "prod-mpp"
    },
    {
      "url": "https://api.agentmail.eu",
      "description": "eu-prod"
    }
  ],
  "security": [
    {
      "Bearer": []
    }
  ],
  "securitySchemes": {
    "Bearer": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "parameters": [
    {
      "name": "pod_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "description": "ID of pod.",
        "title": "PodId"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Name of api key.",
                  "title": "Name"
                },
                "permissions": {
                  "type": "object",
                  "properties": {
                    "inbox_read": {
                      "type": "boolean",
                      "description": "Read inbox details."
                    },
                    "inbox_create": {
                      "type": "boolean",
                      "description": "Create new inboxes."
                    },
                    "inbox_update": {
                      "type": "boolean",
                      "description": "Update inbox settings."
                    },
                    "inbox_delete": {
                      "type": "boolean",
                      "description": "Delete inboxes."
                    },
                    "message_read": {
                      "type": "boolean",
                      "description": "Read messages. Also required to read threads."
                    },
                    "message_send": {
                      "type": "boolean",
                      "description": "Send messages."
                    },
                    "message_update": {
                      "type": "boolean",
                      "description": "Update message labels. Also required to update threads."
                    },
                    "message_delete": {
                      "type": "boolean",
                      "description": "Delete messages. Also required to delete threads."
                    },
                    "label_spam_read": {
                      "type": "boolean",
                      "description": "Access messages labeled spam."
                    },
                    "label_blocked_read": {
                      "type": "boolean",
                      "description": "Access messages labeled blocked."
                    },
                    "label_unauthenticated_read": {
                      "type": "boolean",
                      "description": "Access messages labeled unauthenticated."
                    },
                    "label_trash_read": {
                      "type": "boolean",
                      "description": "Access messages labeled trash."
                    },
                    "draft_read": {
                      "type": "boolean",
                      "description": "Read drafts."
                    },
                    "draft_create": {
                      "type": "boolean",
                      "description": "Create drafts."
                    },
                    "draft_update": {
                      "type": "boolean",
                      "description": "Update drafts."
                    },
                    "draft_delete": {
                      "type": "boolean",
                      "description": "Delete drafts."
                    },
                    "draft_send": {
                      "type": "boolean",
                      "description": "Send drafts."
                    },
                    "webhook_read": {
                      "type": "boolean",
                      "description": "Read webhook configurations."
                    },
                    "webhook_create": {
                      "type": "boolean",
                      "description": "Create webhooks."
                    },
                    "webhook_update": {
                      "type": "boolean",
                      "description": "Update webhooks."
                    },
                    "webhook_delete": {
                      "type": "boolean",
                      "description": "Delete webhooks."
                    },
                    "domain_read": {
                      "type": "boolean",
                      "description": "Read domain details."
                    },
                    "domain_create": {
                      "type": "boolean",
                      "description": "Create domains."
                    },
                    "domain_update": {
                      "type": "boolean",
                      "description": "Update domains."
                    },
                    "domain_delete": {
                      "type": "boolean",
                      "description": "Delete domains."
                    },
                    "list_entry_read": {
                      "type": "boolean",
                      "description": "Read list entries."
                    },
                    "list_entry_create": {
                      "type": "boolean",
                      "description": "Create list entries."
                    },
                    "list_entry_delete": {
                      "type": "boolean",
                      "description": "Delete list entries."
                    },
                    "metrics_read": {
                      "type": "boolean",
                      "description": "Read metrics."
                    },
                    "api_key_read": {
                      "type": "boolean",
                      "description": "Read API keys."
                    },
                    "api_key_create": {
                      "type": "boolean",
                      "description": "Create API keys."
                    },
                    "api_key_update": {
                      "type": "boolean",
                      "description": "Update API keys."
                    },
                    "api_key_delete": {
                      "type": "boolean",
                      "description": "Delete API keys."
                    },
                    "provider_connect": {
                      "type": "boolean",
                      "description": "Sign in to providers as an inbox: connect a provider, authorize an inbox, and mint the\nsign-in keys. Omitted on a new bearer key means false, whatever else the key holds."
                    },
                    "provider_share_owner": {
                      "type": "boolean",
                      "description": "Share the organization owner's name and email with providers at sign-in. One permission\nfor both values."
                    },
                    "account_update": {
                      "type": "boolean",
                      "description": "Update accounts: disable or re-enable an inbox's sign-in at a provider. Reading accounts\nneeds only `inbox_read`."
                    },
                    "pod_read": {
                      "type": "boolean",
                      "description": "Read pods."
                    },
                    "pod_create": {
                      "type": "boolean",
                      "description": "Create pods."
                    },
                    "pod_update": {
                      "type": "boolean",
                      "description": "Update pods."
                    },
                    "pod_delete": {
                      "type": "boolean",
                      "description": "Delete pods."
                    }
                  },
                  "description": "Granular permissions for the API key. When ommitted all permissions are granted. Otherwise, only permissions set to true are granted.",
                  "title": "ApiKeyPermissions"
                }
              },
              "title": "CreateBearerApiKeyRequest"
            },
            {
              "type": "object",
              "properties": {
                "public_key": {
                  "type": "object",
                  "properties": {
                    "kty": {
                      "type": "string",
                      "enum": [
                        "EC"
                      ]
                    },
                    "crv": {
                      "type": "string",
                      "enum": [
                        "P-256"
                      ]
                    },
                    "x": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9_-]{43}$",
                      "minLength": 43,
                      "maxLength": 43,
                      "description": "A 32-byte P-256 coordinate encoded as unpadded base64url.",
                      "title": "PublicJwkCoordinate"
                    },
                    "y": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9_-]{43}$",
                      "minLength": 43,
                      "maxLength": 43,
                      "description": "A 32-byte P-256 coordinate encoded as unpadded base64url.",
                      "title": "PublicJwkCoordinate"
                    }
                  },
                  "required": [
                    "kty",
                    "crv",
                    "x",
                    "y"
                  ],
                  "description": "A public P-256 JWK. The object accepts exactly `kty`, `crv`, `x`, and `y`.\nPrivate key material such as `d`, embedded key IDs, and all other members\nare rejected. The server also rejects coordinates that are not a point on\nP-256.",
                  "title": "PublicJwk"
                },
                "client_id": {
                  "type": "string",
                  "description": "Caller-chosen alias for a public key, unique within the organization and\nreusable after deletion. Accepted in place of `api_key_id` on get, update,\nand delete. Registration is idempotent on it: the same alias returns the\nexisting key, a conflicting one returns `409`. URL-safe; no slash or `@`.",
                  "title": "PublicKeyClientId"
                },
                "name": {
                  "type": "string",
                  "description": "Name of api key.",
                  "title": "Name"
                },
                "permissions": {
                  "type": "object",
                  "properties": {
                    "inbox_read": {
                      "type": "boolean",
                      "description": "Read inbox details."
                    },
                    "inbox_create": {
                      "type": "boolean",
                      "description": "Create new inboxes."
                    },
                    "inbox_update": {
                      "type": "boolean",
                      "description": "Update inbox settings."
                    },
                    "inbox_delete": {
                      "type": "boolean",
                      "description": "Delete inboxes."
                    },
                    "message_read": {
                      "type": "boolean",
                      "description": "Read messages. Also required to read threads."
                    },
                    "message_send": {
                      "type": "boolean",
                      "description": "Send messages."
                    },
                    "message_update": {
                      "type": "boolean",
                      "description": "Update message labels. Also required to update threads."
                    },
                    "message_delete": {
                      "type": "boolean",
                      "description": "Delete messages. Also required to delete threads."
                    },
                    "label_spam_read": {
                      "type": "boolean",
                      "description": "Access messages labeled spam."
                    },
                    "label_blocked_read": {
                      "type": "boolean",
                      "description": "Access messages labeled blocked."
                    },
                    "label_unauthenticated_read": {
                      "type": "boolean",
                      "description": "Access messages labeled unauthenticated."
                    },
                    "label_trash_read": {
                      "type": "boolean",
                      "description": "Access messages labeled trash."
                    },
                    "draft_read": {
                      "type": "boolean",
                      "description": "Read drafts."
                    },
                    "draft_create": {
                      "type": "boolean",
                      "description": "Create drafts."
                    },
                    "draft_update": {
                      "type": "boolean",
                      "description": "Update drafts."
                    },
                    "draft_delete": {
                      "type": "boolean",
                      "description": "Delete drafts."
                    },
                    "draft_send": {
                      "type": "boolean",
                      "description": "Send drafts."
                    },
                    "webhook_read": {
                      "type": "boolean",
                      "description": "Read webhook configurations."
                    },
                    "webhook_create": {
                      "type": "boolean",
                      "description": "Create webhooks."
                    },
                    "webhook_update": {
                      "type": "boolean",
                      "description": "Update webhooks."
                    },
                    "webhook_delete": {
                      "type": "boolean",
                      "description": "Delete webhooks."
                    },
                    "domain_read": {
                      "type": "boolean",
                      "description": "Read domain details."
                    },
                    "domain_create": {
                      "type": "boolean",
                      "description": "Create domains."
                    },
                    "domain_update": {
                      "type": "boolean",
                      "description": "Update domains."
                    },
                    "domain_delete": {
                      "type": "boolean",
                      "description": "Delete domains."
                    },
                    "list_entry_read": {
                      "type": "boolean",
                      "description": "Read list entries."
                    },
                    "list_entry_create": {
                      "type": "boolean",
                      "description": "Create list entries."
                    },
                    "list_entry_delete": {
                      "type": "boolean",
                      "description": "Delete list entries."
                    },
                    "metrics_read": {
                      "type": "boolean",
                      "description": "Read metrics."
                    },
                    "api_key_read": {
                      "type": "boolean",
                      "description": "Read API keys."
                    },
                    "api_key_create": {
                      "type": "boolean",
                      "description": "Create API keys."
                    },
                    "api_key_update": {
                      "type": "boolean",
                      "description": "Update API keys."
                    },
                    "api_key_delete": {
                      "type": "boolean",
                      "description": "Delete API keys."
                    },
                    "provider_connect": {
                      "type": "boolean",
                      "description": "Sign in to providers as an inbox: connect a provider, authorize an inbox, and mint the\nsign-in keys. Omitted on a new bearer key means false, whatever else the key holds."
                    },
                    "provider_share_owner": {
                      "type": "boolean",
                      "description": "Share the organization owner's name and email with providers at sign-in. One permission\nfor both values."
                    },
                    "account_update": {
                      "type": "boolean",
                      "description": "Update accounts: disable or re-enable an inbox's sign-in at a provider. Reading accounts\nneeds only `inbox_read`."
                    },
                    "pod_read": {
                      "type": "boolean",
                      "description": "Read pods."
                    },
                    "pod_create": {
                      "type": "boolean",
                      "description": "Create pods."
                    },
                    "pod_update": {
                      "type": "boolean",
                      "description": "Update pods."
                    },
                    "pod_delete": {
                      "type": "boolean",
                      "description": "Delete pods."
                    }
                  },
                  "description": "Granular permissions for the API key. When ommitted all permissions are granted. Otherwise, only permissions set to true are granted.",
                  "title": "ApiKeyPermissions"
                },
                "expires_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Time at which api key expires. Omitted when it does not expire.",
                  "title": "ExpiresAt"
                }
              },
              "required": [
                "public_key"
              ],
              "description": "Registers a public P-256 JWK at the route's scope. `type` and\n`api_key_id` are server-owned. `name` defaults to\n`AgentID key {first eight fingerprint characters}`; `permissions`\ndefaults to the registering key's, and only grants it holds may be\ntrue; `expires_at` defaults to the registering key's expiry and is\nindependent of that key afterward.",
              "title": "CreatePublicKeyRequest"
            }
          ],
          "description": "A body with `public_key` registers a public-key credential; any other\nbody mints a bearer key.",
          "title": "CreateApiKeyRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Response with status 200",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "api_key_id": {
                "type": "string",
                "description": "ID of api key.",
                "title": "ApiKeyId"
              },
              "api_key": {
                "type": "string",
                "description": "API key."
              },
              "prefix": {
                "type": "string",
                "description": "Prefix of api key.",
                "title": "Prefix"
              },
              "name": {
                "type": "string",
                "description": "Name of api key.",
                "title": "Name"
              },
              "pod_id": {
                "type": "string",
                "description": "Pod ID the api key is scoped to. If set, the key can only access resources within this pod.",
                "title": "PodScopeId"
              },
              "inbox_id": {
                "type": "string",
                "description": "Inbox ID the api key is scoped to. If set, the key can only access resources within this inbox.",
                "title": "InboxScopeId"
              },
              "permissions": {
                "type": "object",
                "properties": {
                  "inbox_read": {
                    "type": "boolean",
                    "description": "Read inbox details."
                  },
                  "inbox_create": {
                    "type": "boolean",
                    "description": "Create new inboxes."
                  },
                  "inbox_update": {
                    "type": "boolean",
                    "description": "Update inbox settings."
                  },
                  "inbox_delete": {
                    "type": "boolean",
                    "description": "Delete inboxes."
                  },
                  "message_read": {
                    "type": "boolean",
                    "description": "Read messages. Also required to read threads."
                  },
                  "message_send": {
                    "type": "boolean",
                    "description": "Send messages."
                  },
                  "message_update": {
                    "type": "boolean",
                    "description": "Update message labels. Also required to update threads."
                  },
                  "message_delete": {
                    "type": "boolean",
                    "description": "Delete messages. Also required to delete threads."
                  },
                  "label_spam_read": {
                    "type": "boolean",
                    "description": "Access messages labeled spam."
                  },
                  "label_blocked_read": {
                    "type": "boolean",
                    "description": "Access messages labeled blocked."
                  },
                  "label_unauthenticated_read": {
                    "type": "boolean",
                    "description": "Access messages labeled unauthenticated."
                  },
                  "label_trash_read": {
                    "type": "boolean",
                    "description": "Access messages labeled trash."
                  },
                  "draft_read": {
                    "type": "boolean",
                    "description": "Read drafts."
                  },
                  "draft_create": {
                    "type": "boolean",
                    "description": "Create drafts."
                  },
                  "draft_update": {
                    "type": "boolean",
                    "description": "Update drafts."
                  },
                  "draft_delete": {
                    "type": "boolean",
                    "description": "Delete drafts."
                  },
                  "draft_send": {
                    "type": "boolean",
                    "description": "Send drafts."
                  },
                  "webhook_read": {
                    "type": "boolean",
                    "description": "Read webhook configurations."
                  },
                  "webhook_create": {
                    "type": "boolean",
                    "description": "Create webhooks."
                  },
                  "webhook_update": {
                    "type": "boolean",
                    "description": "Update webhooks."
                  },
                  "webhook_delete": {
                    "type": "boolean",
                    "description": "Delete webhooks."
                  },
                  "domain_read": {
                    "type": "boolean",
                    "description": "Read domain details."
                  },
                  "domain_create": {
                    "type": "boolean",
                    "description": "Create domains."
                  },
                  "domain_update": {
                    "type": "boolean",
                    "description": "Update domains."
                  },
                  "domain_delete": {
                    "type": "boolean",
                    "description": "Delete domains."
                  },
                  "list_entry_read": {
                    "type": "boolean",
                    "description": "Read list entries."
                  },
                  "list_entry_create": {
                    "type": "boolean",
                    "description": "Create list entries."
                  },
                  "list_entry_delete": {
                    "type": "boolean",
                    "description": "Delete list entries."
                  },
                  "metrics_read": {
                    "type": "boolean",
                    "description": "Read metrics."
                  },
                  "api_key_read": {
                    "type": "boolean",
                    "description": "Read API keys."
                  },
                  "api_key_create": {
                    "type": "boolean",
                    "description": "Create API keys."
                  },
                  "api_key_update": {
                    "type": "boolean",
                    "description": "Update API keys."
                  },
                  "api_key_delete": {
                    "type": "boolean",
                    "description": "Delete API keys."
                  },
                  "provider_connect": {
                    "type": "boolean",
                    "description": "Sign in to providers as an inbox: connect a provider, authorize an inbox, and mint the\nsign-in keys. Omitted on a new bearer key means false, whatever else the key holds."
                  },
                  "provider_share_owner": {
                    "type": "boolean",
                    "description": "Share the organization owner's name and email with providers at sign-in. One permission\nfor both values."
                  },
                  "account_update": {
                    "type": "boolean",
                    "description": "Update accounts: disable or re-enable an inbox's sign-in at a provider. Reading accounts\nneeds only `inbox_read`."
                  },
                  "pod_read": {
                    "type": "boolean",
                    "description": "Read pods."
                  },
                  "pod_create": {
                    "type": "boolean",
                    "description": "Create pods."
                  },
                  "pod_update": {
                    "type": "boolean",
                    "description": "Update pods."
                  },
                  "pod_delete": {
                    "type": "boolean",
                    "description": "Delete pods."
                  }
                },
                "description": "Granular permissions for the API key. When ommitted all permissions are granted. Otherwise, only permissions set to true are granted.",
                "title": "ApiKeyPermissions"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "description": "Time at which api key was created.",
                "title": "CreatedAt"
              }
            },
            "required": [
              "api_key_id",
              "api_key",
              "prefix",
              "name",
              "created_at"
            ],
            "title": "CreateApiKeyResponse"
          }
        }
      }
    },
    "400": {
      "description": "Error response with status 400",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of error.",
                "title": "ErrorName"
              },
              "code": {
                "type": "string",
                "description": "Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.",
                "title": "ErrorCode"
              },
              "message": {
                "type": "string",
                "description": "Error message.",
                "title": "ErrorMessage"
              },
              "errors": {
                "description": "Validation errors. Each entry has a path and a message identifying the invalid field."
              },
              "fix": {
                "type": "string",
                "description": "The concrete next action that resolves the error.",
                "title": "ErrorFix"
              },
              "docs": {
                "type": "string",
                "description": "Link to the error reference entry for this code.",
                "title": "ErrorDocs"
              }
            },
            "required": [
              "name",
              "errors"
            ],
            "title": "ValidationErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Error response with status 404",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of error.",
                "title": "ErrorName"
              },
              "code": {
                "type": "string",
                "description": "Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.",
                "title": "ErrorCode"
              },
              "message": {
                "type": "string",
                "description": "Error message.",
                "title": "ErrorMessage"
              },
              "fix": {
                "type": "string",
                "description": "The concrete next action that resolves the error.",
                "title": "ErrorFix"
              },
              "docs": {
                "type": "string",
                "description": "Link to the error reference entry for this code.",
                "title": "ErrorDocs"
              }
            },
            "required": [
              "name",
              "message"
            ],
            "title": "ErrorResponse"
          }
        }
      }
    }
  }
}
```