Create

Mints a new API key for the CALLER's own account and returns the plaintext exactly once in this response — it is never retrievable again. name is required and cannot be blank: an unnamed key is a working credential nobody can identify to revoke later, so an empty or whitespace-only name is rejected with 400 missing_fields rather than silently minting an anonymous key. scope is optional and space-delimited, in the same vocabulary OAuth grants (enforcer:read | enforcer:write | enforcer:admin | policy:self | enforcer:<tag>.<effect>); the key stores it and the response echoes it. A key never exceeds its owner's role and permissions, and a scope narrows it further. A caller whose own credential carries a scope may only mint at or below it (the coarse ladder read < write < admin; a fine scope is covered by its own tag at an equal-or-wider effect or by a covering coarse scope) and is refused with 403 insufficient_scope otherwise; such a caller that omits scope gets a key carrying its own scope, never an unscoped one. An unscoped caller (a login session, an unscoped API key) may mint any scope or none. An unknown scope is 400 invalid_scope. expires_at is optional, RFC 3339, and must be in the future (400 invalid_expires_at otherwise); once it passes the key is refused with 401 on both the HTTP X-API-Key path and the gRPC transport, exactly like a revoked key. Omitted, the key never expires. The response records created_by, the account that minted the key. A caller presenting an agent (ag_, or an agent client_credentials token) or portal-link credential may never mint a key: 403 agent_cannot_mint (AGENTS_CONTRACT §5.3).