Account-scoped
Reaches every project in the account. Leave the project unset when minting. Good for an internal tool that spans projects.
API keys authenticate every call to the REST API and to the MCP server. Each key carries a name, a scope, and a secret that is shown exactly once. The secret is stored only as a non-reversible hash: uMarker can verify a key but can never reveal it again.
These keys are separate from the widget’s tokens and from the credentials that connect issue trackers. They exist solely to authorize the REST API.
A key is minted at one of two scopes, and that scope is enforced on every API request:
Account-scoped
Reaches every project in the account. Leave the project unset when minting. Good for an internal tool that spans projects.
Project-scoped
Reaches exactly one project and nothing else. Choose the project when minting. Prefer this: it’s the tighter blast radius.
A request for any project outside the key’s scope, or in another account, is rejected 403 with no data exposed. Cross-tenant access is impossible.
Go to API Keys in the dashboard (/api-keys).
Give the key a name (up to 100 characters), something that identifies where it’s used, e.g. support-inbox-importer.
Choose a scope. For a project key, also pick the project it’s limited to. (A project-scoped key without a project is rejected, and you’ll be asked to choose one.)
Create the key. The full secret is displayed exactly once. Copy it immediately.
The secret is formatted md_live_ followed by 40 characters:
md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAfter creation, the key list shows metadata only, never the full secret:
| Field | Description |
|---|---|
| Name | The label you gave it. |
| Scope | Account, or the project’s name for a project-scoped key. |
| Prefix | The first 12 characters (md_live_…), for identifying the key at a glance. |
| Created by | Who minted it. Reads former member once that person has been deleted from the account. |
| Last used | When the key last authenticated a request, written on every successful call. |
| Actions | The revoke control, while the key is live. Once revoked it reads revoked instead: the key stays in the list, as the record that it existed. |
The Created by column is the one you want when a teammate leaves: it tells you which credentials are still in their hands. Last used is for spotting keys that are no longer in use (safe to revoke), or a key that’s suddenly active when it shouldn’t be.
Send the secret on every request, either as a bearer token or in the X-Api-Key header:
Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX-Api-Key: md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA missing key returns 401 API key required.; an unknown or revoked key returns 401 Invalid or revoked API key. See the REST API reference for the endpoints and full error table.
A key is not detached from the person who minted it. uMarker re-checks them on every request, and answers 403 with a message naming the reason when:
Deleting a member outright is different: it revokes their keys on the spot, permanently.
The developer API is bucketed per key, not per IP address: every key gets an allowance of its own rather than sharing one with every other caller behind the same address, and a single misbehaving key can be isolated. The defaults are 300 requests per minute per key, and above that a wider 1,200 per minute per IP address — that second ceiling is shared, so keys calling from one egress address do still meet each other at it.
Exceeding the limit returns 429 Too Many Requests with a Retry-After header giving the seconds to wait:
HTTP/1.1 429 Too Many RequestsRetry-After: 30Design clients to back off on 429 rather than retry tightly. For bulk reads, page through results (per_page up to 100) instead of hammering the endpoint.
Revoke a key the moment it’s no longer needed or may have leaked. Revocation is immediate: the next request using that key is rejected 401.
On the API Keys page, find the key by name or prefix.
Revoke it. uMarker marks it revoked and confirms.
Any subsequent call with that key fails closed with 401 Invalid or revoked API key.
There is no un-revoke and no in-place rotation. To rotate a key, mint a new one, deploy it to your client, and revoke the old one once traffic has moved over.
See Security & privacy overview and Tenancy & data model for how these guarantees fit the wider platform.