Authentication
Make an API key, send it in the Authorization header, keep it safe, and know when it stops working.
Every request to the API carries an API key. A key belongs to your workspace, not to a person. It can read and change everything on the workspace's boards.
Get a key
Owners and admins make keys in the app. Members don't see the page.
- Open API keys in the sidebar, under Workspace.
- Select New key.
- Give it a name of up to 60 characters. Name it after the code that will use it, so you can tell your keys apart.
- Choose when it expires: never, or after 30, 90 or 365 days.
- Select Create key, then copy the key.
The key is shown once. We don't keep it and can't show it again. If you lose it, make a new key.
A workspace can have up to 50 live keys at a time. Revoked and expired keys don't count.
The key's format
A key starts with mf_live_, followed by 52 lowercase letters and digits. These docs write it as mf_live_…. The prefix lets you, a log search or a secret scanner spot a key at a glance.
The list in the app shows only the start and the end of each key, so you can tell which key is which.
Send the key
Send the key in the Authorization header: the word Bearer, one space, then the key.
Authorization: Bearer mf_live_…For example, with the key in an environment variable:
curl https://api.melonforce.com/v1/boards \
-H "Authorization: Bearer $MELONFORCE_API_KEY"The header must be exactly that. Anything else, such as a lowercase bearer or a second space, is refused.
The API reads a key only from that header. A key in the query string, the body or a cookie is not read.
One workspace per key
A key reaches only the workspace it was made in. No route takes a workspace ID: the workspace always comes from the key. A board, column, view, group or item ID from another workspace answers as if it did not exist, and nothing changes. In a path, that is 404 NOT_FOUND.
Keep keys safe
- Keep keys on your servers, in an environment variable or a secret store.
- Never put a key in a web page, a mobile or desktop app, or git. The API sends no CORS headers, so a browser won't send a call that carries a key.
- If a key may have leaked, revoke it in the app and make a new one.
- To replace a key, make a new one, switch your code to it, then revoke the old one.
When a key stops working
A key stops working at once when:
- someone revokes it in the app;
- it expires;
- the person who made it leaves the workspace or stops being an owner or admin;
- the workspace is suspended, closed or deleted.
A key that stopped never works again, even if its maker comes back or the workspace becomes active again. Make a new key and switch your code to it.
When keys stop because their maker left the workspace or lost the role, or because the workspace was suspended or closed, the workspace's owners get an email that names the keys and says why.
Refused keys
Every key that doesn't work gets the same answer: 401 UNAUTHENTICATED, with the header WWW-Authenticate: Bearer. The answer never says why, whether the key is mistyped, unknown, revoked, expired or stopped for one of the reasons above.
{ "error": { "code": "UNAUTHENTICATED" } }If a key that worked starts to get this answer, an owner or admin can see in the app's list when the key stopped and why.
Too many refused keys from one address get 429 RATE_LIMITED instead. Only keys in the key's format count toward this: unknown, revoked or expired keys, or keys that stopped working. A malformed header or key gets 401 and isn't counted. See Rate limits.
What a key acts as
A key acts with the board powers of the owner or admin who made it. It can do everything on the workspace's boards, deleting and restoring boards included.
- Its changes carry its name. What a key changes shows in the app with the key's name and an "API key" tag. In answers, an item or note the key changed has
updatedByTypeset toapi_key, a change in a change log hasactorTypeset toapi_key, andapiKeysgives the key's name. - Its posts are its own. An update a key posts shows as a post from the key. A key can edit and delete its own posts, and no one else's.
- It can't claim items. Claim puts the person asking on an item, and a key isn't a person. To assign someone, set the item's person column with an update of the item instead.
- It can't use "Me". "Me" in a filter means the person asking, so a key can't use it, in a query or in a saved view it runs. Such a query answers 400
QUERY_INVALID. Filter by a named person instead.
Routes for signed-in people
Routes for managing members, invitations, API keys and Gmail are only for people signed in to the app. A request to one of them with an Authorization header gets 403 FORBIDDEN, and nothing is read:
{ "error": { "code": "FORBIDDEN", "details": { "reason": "session_required" } } }These routes aren't in these docs. A key can list the workspace's members, so it can set a person column.