Keylayer keys, minting keys and child keys
A Keylayer key starts with kl_k_ and is what your code sends to the relay; Keylayer swaps it for your provider key on the way out. A minting key starts with kl_m_ and only creates keys below it. Every key belongs to one credential and never gets looser limits than the key it was minted from. A key you mint lasts 1 hour by default and 365 days at most.
Key types
| Key | Starts with | What it does | On the relay |
|---|---|---|---|
| Keylayer key | kl_k_ | Sends requests to the provider through the relay | Accepted |
| Minting key | kl_m_ | Mints child keys below it | Refused with 401 invalid_token |
| Provider key | The provider's own format | The real key from OpenAI, Anthropic and so on | Never sent by your code |
When you mint a key in the dashboard, Kind sets its type: Can't mint keys of its own makes a Keylayer key and Can mint keys of its own makes a minting key. A minting key can also mint keys from your own code through the Keylayer API. Keep a minting key out of browsers and public code: whoever holds it can mint keys up to its own limits.
Under Keys it mints, a minting key can set two rules for every key minted below it. Label set to Required refuses a mint without a label with 400 label_required. Live at most, from 1 minute to 365 days, shortens a longer lifetime instead of refusing the mint. Through the Keylayer API, they're the policy fields require_label, set to true, and max_child_ttl, in seconds. Null clears either one. Keys already minted keep their label and lifetime.
Credentials
A credential is one provider key added to Keylayer, with the hosts it can reach and the region where its limits are checked. You add one under Credentials with Add a credential and type the provider key only in the vault window. Keylayer stores it encrypted, and no screen shows it again.
Adding a credential creates two keys:
- A root minting key, kept in your vault. Every key you mint in the dashboard is minted from it.
- A Keylayer key with no limits of its own, shown once in the vault as Your new key.
A credential lasts 365 days from the day you add it, and no key below it can outlive it. Add a new credential before then to keep your agents running.
On the free plan, a credential relays at most 5,000 requests per UTC day and 60 a minute across all its keys, and a workspace can have 10 live credentials and add 20 per UTC day. Past those, you get 429 daily_cap, 429 rate_limited, 409 credential_limit or 429 enroll_daily_cap. A credential revoked today still counts toward the 10 until 00:00 UTC. Pro allows 100 live credentials, with no daily cap on requests or new credentials, and the relay's flood limit still applies. On every plan, a workspace starts at most 10 enrollments an hour, and past that gets 429 enroll_rate_limited. Pricing compares the plans.
Child keys and limit clamping
Every key you mint is a child of the key that minted it. When you mint or edit a child key, Keylayer clamps each limit to the parent's:
- For numbers, the smaller value wins: requests a minute, requests at once, and each period of request caps and spend caps. Where only the parent sets a limit, the child gets the parent's.
- A parent with a hard spend cap keeps the child's cap hard.
- Methods are the ones both allow, and each path pattern and IP range must sit inside one of the parent's. If no method is left, or a pattern or range falls outside, the mint is refused with 400 invalid_policy.
- The child stops working no later than its parent.
- Escape hatches are never inherited. See admin routes and escape hatches.
On top of that, every request is checked against the limits of the key and of every key above it. Narrowing a minting key's limits binds every key below it at once.
How deep keys go and how many
- Your root minting key sits at depth 0, and keys you mint in the dashboard sit at depth 1.
- A minting key can sit at depth 2 at most, and any key at depth 3 at most. A deeper mint is refused with 400 invalid_policy.
- A credential holds at most 500 live keys on the free plan and 5,000 on Pro. Minting keys below the root can only mint while it has fewer than 450, or 4,950 on Pro, which keeps 50 free for you. Past the limit, a mint gets 409 too_many_keys. Expired and revoked keys don't count. When Pro ends, no key is revoked, but mints get 409 too_many_keys until the credential is back under the free plan's limit.
- Mints and limit changes from the dashboard share 60 a minute per credential, and all minting keys below the root share another 60. Limit changes also stop at 100 per UTC day for each of the two, and provider key rotations at 100 per UTC day per credential. Past any of these, you get 429 mint_rate_limited, until 00:00 UTC for the daily ones.
- On the free plan, a workspace can mint 1,440 keys per UTC day. Past that, you get 429 mint_quota_exceeded. Pro has no daily mint limit.
Listing keys
A minting key lists itself and the keys below it: send GET https://api.keylayer.dev/v1/keys with the minting key as the bearer token. The answer holds keys and next_cursor. The first page starts with the minting key itself, then come the keys below it, newest first.
curl "https://api.keylayer.dev/v1/keys?limit=500" \
-H "Authorization: Bearer $KEYLAYER_MINTING_KEY"limitsets 1 to 500 keys a page, 100 if you leave it out. Any other value gets 400 invalid_limit.- For the next page, send the last answer's
next_cursoras it is incursor.next_cursoris null on the last page, and a cursor in another form gets 400 invalid_cursor. - All minting keys below the root share 60 lists a minute per credential. Past that, you get 429 rate_limited, and retry-after says when to try again.
Lifetime
Every key gets a lifetime when you mint it: 1 hour, the default, For a number of minutes, hours or days, or Until a time in UTC. For takes 1 minute to 365 days and Until any time up to 365 days out. A lifetime never runs past the parent's or the Live at most of a minting key above it, and can't be extended later.
The Stops working (UTC) limit is different. Until it passes, you can move it under Edit limits, earlier or later, as long as it stays within the lifetime. To keep the option of extending access, mint with a long lifetime and a near Stops working time.
Once the lifetime runs out, the key and every key below it get 401 key_expired. Once Stops working passes, they get 401 expired, or 401 unknown_key after Keylayer deletes them. Either way, the key can't be brought back.
Labels
A label is an optional name of 1 to 64 characters, unless a minting key above it requires one. It shows in the Keys list, where a key without one reads No label, and on the vault's approval screen. You can't change it after minting.
Pausing a key
There's no pause button. To pause a key, click Edit limits on its row, set Status to Suspended, click Continue and then Approve in your vault. To resume it, set Status back to Active the same way.
A paused key gets 403 suspended, and so does every key below it, which the Keys list marks Parent suspended.
Edit limits only appears on keys minted straight from your vault's root key that the vault keeps. That covers the key shown when you add a credential and keys you mint in the dashboard with Keep it in the vault, so it can be revealed later checked.
Revoking a key
Click Revoke on the key's row and confirm with Revoke key. The key stops working right away, and so does every key below it. You can't undo a revoke.
Revoking needs a Google sign-in from the last 9 minutes. If yours is older, the dashboard asks you to Confirm it's you; click Continue with Google and pick your account again.
To stop everything at once, click Revoke on the credential under Credentials. Every key below it stops, and the dashboard links to the provider's key page so you can delete the provider key there too.
Rotating the provider key
Your Keylayer keys keep working when you replace the provider key. Click Rotate on the credential, click Continue and Open vault, then paste the new provider key in the vault window. The vault confirms with The credential uses its new upstream key now. Then delete the old key at the provider.
What happens to running requests
Keylayer checks every running request again every 10 seconds. Pausing, revoking or reaching the expiry stops a running request, streams included, within about 10 seconds. Keylayer can't undo work the provider already did. Other limit changes, such as a lower spend cap or rate, apply from the next request; see how fast changes apply.
Updated