How keys work #
A team can have several keys. Give each backend its own key, so you can revoke one and the rest keep working.
A key is known by its id, which starts with key_. The key itself, which starts with ml_, is returned once, when it is made. Meme Lemur stores only a hash of it and cannot show it again.
Regular keys and admin keys #
A key is one of two kinds, and its kind says which.
| Kind | What the key can call |
|---|---|
regular |
Everything an editor can, except the API key routes. That is making memes, templates, the library, feedback, usage and credits, and changing settings and spaces. |
admin |
Every route under /v1. |
Only an admin key can do these:
- Invite a person, remove one or change a person's role, and list the people and the invitations.
- Store or delete the team's model key.
- Make, list and revoke API keys.
A regular key that calls one of them gets 403:
{ "error": "this route needs an admin API key" }A new key is regular unless you ask for an admin key. Put a regular key in a backend that makes memes, and keep an admin key for the jobs that need one. A regular key that leaks cannot make more keys, let anyone in, or change which model account pays.
A key made before keys had kinds is an admin key, so it can still call everything it could.
The kind of a key never changes. To change what a backend can do, make a key of the other kind and revoke the old one.
List the keys #
GET /v1/keys
Returns every key the team has had, oldest first, revoked ones included.
curl https://api.memelemur.com/v1/keys \
-H "Authorization: Bearer $MEMELEMUR_ADMIN_KEY"{
"keys": [
{ "id": "key_p11rk7ujt5ehctby", "label": "initial", "kind": "admin", "dailyCap": null, "createdAt": "2026-10-02T00:57:15.707Z", "revokedAt": null, "current": true },
{ "id": "key_j15z8f8skojfdb1l", "label": "billing service", "kind": "regular", "dailyCap": 500, "createdAt": "2026-10-02T00:58:17.099Z", "revokedAt": null, "current": false }
]
}kind is regular or admin. dailyCap is the key's daily cap, or null for none. current is true for the key this request was made with. revokedAt is null for a key that works.
Make a key #
POST /v1/keys
| Field | Type | What it does |
|---|---|---|
label |
string, up to 80 characters | A name to tell the keys apart, such as the service that uses it. Empty when left out. |
kind |
regular or admin |
The kind of key to make. The default is regular. |
dailyCap |
whole number from 0 to 1,000,000, or null | The most generate and match calls the key may make in a UTC day. Null, the default, is no cap of the key's own. See cap a key. |
curl https://api.memelemur.com/v1/keys \
-H "Authorization: Bearer $MEMELEMUR_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"label": "billing service"}'The response is 201. apiKey is the new key, and this is the only time it is returned:
{
"apiKey": "ml_8fq2c0h1x7m4k9d3t6b5w2n8r1p7s4vy",
"key": { "id": "key_j15z8f8skojfdb1l", "label": "billing service", "kind": "regular", "dailyCap": null, "createdAt": "2026-10-02T00:58:17.099Z", "revokedAt": null }
}It returns 400 for a kind that is not one of the two, and for a field other than label, kind and dailyCap.
Cap a key #
PATCH /v1/keys/:keyId
Sets or removes the key's daily cap: the most generate and match calls it may make in a UTC day. Give each integration its own key with a cap, and one integration cannot use up what your team has. A key with no cap has only the team's limits.
| Field | Type | What it does |
|---|---|---|
dailyCap |
whole number from 0 to 1,000,000, or null | The new cap. Null removes it. Required. |
curl -X PATCH https://api.memelemur.com/v1/keys/key_j15z8f8skojfdb1l \
-H "Authorization: Bearer $MEMELEMUR_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"dailyCap": 500}'{
"key": { "id": "key_j15z8f8skojfdb1l", "label": "billing service", "kind": "regular", "dailyCap": 500, "createdAt": "2026-10-02T00:58:17.099Z", "revokedAt": null }
}Every generate and match call the key makes counts when it arrives, whether a new meme or one from the pool answers it, and whether or not it then succeeds. A regenerate counts once. Renders and reads do not count. A cap set during the day counts the calls the key already made that day. The count starts again at 00:00 UTC, and GET /v1/usage has each capped key's count today.
At the cap, the key's generate and match calls return 429 until midnight UTC. Your team's other keys keep working. Limits and errors has the response.
Who may change a cap is who may revoke the key: an owner and an admin key for any key, and an editor for a regular key.
Errors #
| Status | When |
|---|---|
| 400 | dailyCap is missing, is not a whole number, or is out of range. |
| 403 | A signed-in editor tried to change an admin key. |
| 404 | Your team has no key with that id. |
Revoke a key #
POST /v1/keys/:keyId/revoke
A revoked key returns 401 from the next request on. It stays in the list with revokedAt set.
curl -X POST https://api.memelemur.com/v1/keys/key_p11rk7ujt5ehctby/revoke \
-H "Authorization: Bearer $MEMELEMUR_ADMIN_KEY"{
"key": { "id": "key_p11rk7ujt5ehctby", "label": "initial", "kind": "admin", "createdAt": "2026-10-02T00:57:15.707Z", "revokedAt": "2026-10-02T00:59:02.562Z" }
}A key cannot revoke itself. That call returns 409, so one mistaken request cannot lock a team out. Revoke a key with another of the team's admin keys. Revoking a key that is already revoked returns it unchanged.
Errors #
| Status | When |
|---|---|
| 403 | A signed-in editor tried to revoke an admin key. An owner or an admin key can. |
| 404 | Your team has no key with that id. |
| 409 | The key in the path is the key the request was made with. |
Replace a key #
- Make a new key of the same kind.
- Switch your backend to the new key.
- Revoke the old key. Make that request with an admin key other than the old one, or do it signed in.
Both keys work between the first step and the third, so no call fails while you switch.
Who can manage keys #
| Regular keys | Admin keys | |
|---|---|---|
| An admin key | Make, list, cap and revoke | Make, list, cap and revoke |
| A signed-in owner | Make, list, cap and revoke | Make, list, cap and revoke |
| A signed-in editor | Make, list, cap and revoke | None of them |
A signed-in member and a regular key get 403 from all four routes.
An editor's list leaves the admin keys out. When an editor asks for an admin key or tries to revoke one, the call returns 403 with creating an admin API key needs the owner role or revoking an admin API key needs the owner role.
The operator, who is whoever runs Meme Lemur for you, can also make a key of either kind for your team and revoke one.