POST /v1/organizations/:orgId/api-keys

To give one of your customers their own credential, mint a key directly against that customer's child organization. You call this with your parent (org:admin) key; the new key belongs to the child named in the path and carries only the access you choose. The plaintext secret comes back once, in this response, and can never be retrieved again.

A child key is a least-privilege credential. Mint a key that can read content for one customer, another that can run ads for another - each scoped to exactly one child org and exactly the scopes that customer's integration needs.

What the child key can be granted

scopes must be a subset of your own key's scopes - you cannot hand a child more access than you hold. And org:admin is never delegable: a child key can never run the control plane (mint its own children, move projects, drain wallets). Request it and the call is rejected with 403 FORBIDDEN_SCOPE.

scopes is required — pass at least one. A key with no scopes is denied on every route, so a scope-less mint is rejected with 422 VALIDATION. See API keys → child keys for the subsetting rules.

Example

curl -X POST https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/api-keys \
  -H "Authorization: Bearer $LAYERS_PARENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-content-sync",
    "scopes": ["content:read", "content:write"],
    "env": "live"
  }'

{
  "apiKey": {
    "id": "key_c2037bb9-354d-4662-96b7-97a28ad6b6e1",
    "organizationId": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
    "name": "acme-content-sync",
    "prefix": "lp_live_ABCDEFGHJKMNPQRS",
    "env": "live",
    "scopes": ["content:read", "content:write"],
    "rateLimitTier": "standard",
    "status": "active",
    "createdAt": "2026-06-03T18:14:02.187Z",
    "lastUsedAt": null,
    "rotatedAt": null,
    "revokedAt": null,
    "graceUntil": null,
    "supersededBy": null
  },
  "secret": "lp_live_...",
  "warning": "Store this secret now. It cannot be retrieved again. Rotate the key if it's lost."
}

Field notes

• secret is the full credential the child integration sends as Authorization: Bearer <secret>. It appears only here - copy it into your secrets manager before you do anything else.
• prefix is the public, non-secret lookup handle. It's safe to log and store; it is not the secret.
• id (key_…) is the public key identifier - use it to list, rotate, or delete the key. It also appears in audit-log attribution.
• scopes echoes exactly what was granted - the subset that survived the check.

Errors

See also

• List child keys - masked view of every key on a child.
• Rotate - zero-downtime secret rollover with a 24h grace.
• Delete - immediate revoke, no grace.
• API keys → child keys - scope subsetting and the org:admin rule.
• Organizations - how sub-organizations model your customers.