Skip to content
Sign inRequest access

API keys & rate limits

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.

  1. Go to API Keys in the dashboard (/api-keys).

  2. Give the key a name (up to 100 characters), something that identifies where it’s used, e.g. support-inbox-importer.

  3. 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.)

  4. 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

After 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A 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:

  • The account is suspended by the platform.
  • The minter is suspended or banned. Suspension is uMarker’s reversible lever: reactivate the person and their keys work again, which revoking could not undo.
  • The minter’s seat is paused because the plan no longer covers everyone on the team. Free a seat or upgrade, and the same key resumes.
  • The plan no longer includes API access (above).

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 Requests
Retry-After: 30

Design 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.

  1. On the API Keys page, find the key by name or prefix.

  2. Revoke it. uMarker marks it revoked and confirms.

  3. 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.

  • Secrets are stored only as a non-reversible SHA-256 hash, never retrievable in plaintext through any UI, API response, or log.
  • Scope and tenant are re-checked server-side on every request; there’s no trust in the client.
  • Revocation takes effect on the next call, with no lingering grace window.
  • Every mint and every revoke is written to the audit log — uMarker’s internal record, which identifies the key by its id, not by the name you gave it. It is not surfaced in your dashboard, and these entries are kept for 30 days.
  • API keys are a separate auth surface from the widget’s tokens; the two never overlap.

See Security & privacy overview and Tenancy & data model for how these guarantees fit the wider platform.