create_api_key
Issues a CHILD API key, from the calling key — RESERVED for MCP calls authenticated by an API key carrying the 'emit_keys' scope (a session/JWT, with no 'parent' key to inherit from, is refused in every case). The granted key is the INTERSECTION of the REQUESTED scopes with the scopes of THE CALLING KEY, not a fixed independent ceiling — a key can never grant more than it holds itself. ⚠️ 'emit_keys' and 'admin' are removed from the issued key in every case, EVEN if explicitly requested and even if the calling key carries them: delegation never goes beyond ONE level — a child key can never itself issue or administer. What is dropped (unknown scope, outside the caller's scopes, or forbidden by nature) is declared in excludedScopes with the reason for each exclusion — no partial grant is returned silently. A call for which NO scope would survive this filtering is REFUSED as a whole: nothing is created. expiresInDays omitted sets a default expiration (90 days) — an issued key is not ever created without an expiration, unlike a key set up from the interface. The PLAINTEXT value of the key (key) is returned ONCE ONLY, in this response: it can never be read again afterwards (only its prefix remains visible in the settings of the owner account). Shares the same hourly issuance cap as manual key creation in the account settings (same account, same counter) — a refusal returns the reopening time. The ACCOUNT can only hold a bounded number of live keys (not revoked, not expired, child keys included): at the cap, the call is REFUSED, nothing is created and no existing key is revoked. A PARENT key also holds only a bounded number of LIVE children (same cap for all plans): at the cap, the call is refused — revoke_api_key revokes a child you no longer use. ⚠️ The PLAINTEXT value of the key enters the CONTEXT of your model (this response): it is entrusted to the agent or process that carries it, without being copied elsewhere, and is revoked when its agent stops. One key per agent that has its own connection (process, subagent with an inline-defined MCP server): this is what prevents two agents from getting mixed up on a single key. Each call creates a DISTINCT key: two identical calls issue TWO keys and not one (no deduplication).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the child key (1-100 characters), shown in the settings of the account owner like their other keys. | |
| scopes | Yes | The scopes REQUESTED for the child key. The granted key is THE INTERSECTION of this set with the scopes of THE CALLING KEY — not a fixed independent ceiling. `emit_keys` and `admin` are removed in every case, even if they are explicitly requested and even if the calling key itself carries them: an issued key can never itself issue or administer. What is dropped (unknown scope, outside the caller's scopes, or forbidden by nature) is declared in the response (`excludedScopes`) rather than silently, with the reason for each exclusion. | |
| projectIds | No | Restricts the child key to these projects (allowlist). As with `scopes`, the child key cannot reach wider than THE CALLING KEY: if the caller is itself bounded (project allowlist or per-set scope), the requested list is INTERSECTED with what the caller actually reaches — and if NOTHING is requested here while the caller IS bounded, the child inherits EXACTLY the projects reachable by the caller (not 'unrestricted'). What is dropped (requested project out of reach) is declared in the response (`excludedProjectIds`). Omitted or empty WHEN THE CALLER IS NOT BOUNDED = no per-project restriction (inherited from the standard behavior of an API key — actual access stays governed by the projects the ACCOUNT owns or shares, and this field does not widen it). | |
| description | No | Free-form description, optional. | |
| expiresInDays | No | Lifetime in days before expiration. Default: 90 days if omitted — an issued key therefore has a default expiration in every case (unlike a key created from the interface, which can be set to "never expire"). |