Skip to Content
APIAuthentication

Authentication

Workspace / admin: API keys

API keys are for a single workspace and can be created by the owner or admin. They provide access to workspace and admin-style routes (markups, webhooks, workspaces, users, etc.). More granular permissions may be introduced in the future.

API keys must be kept secret, stored securely, and used only for server-to-server communication. Treat them like passwords.

Creating an API key

API keys can only be created through the MarkUp web application. Workspace owners and admins can create API keys by following these steps:

  1. Log in to MarkUp.io 
  2. Navigate to your workspace settings
  3. Go to the Developer Settings section
  4. Follow the onboarding wizard to create your API key

The wizard will guide you through configuring scopes and permissions for your API key.

Pass the API key as a Bearer token in the Authorization header.

Curl - Example request with API key secret
curl https://api.markup.io/api/v2/webhook-registrations \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Content-Type: application/json" \
    -H "Markup-API-Version: 2023-02-22"

Feedback: exchange token

For embedded feedback (threads, comments, viewing markups in your app), use the exchange token flow instead of an API key.

Creating an SDK Installation

Before using the exchange token flow, you need to create an SDK installation through the MarkUp web application. Workspace owners and admins can create one from Workspace settings → Developer Portal → SDK tab, using the Create SDK Installation dialog. It walks you through:

  • Generating an RSA key pair (RS256) and pasting the public key — MarkUp stores it as the installation’s signing key to verify your JWTs.
  • Configuring allowed origins for your application.

You come away with a public key (used in the SDK and on exchange requests) and, optionally, a linked markup.

For the full walkthrough and the SDK integration guide, see Create an SDK installation and SDK authentication.

Exchange token flow

Once your installation is configured:

  1. Get Installation Configuration — GET /api/v2/auth/config (with publicKey or installation context) to get signing algorithm and expected claims.
  2. Exchange Token — Your backend signs a JWT with your secret; the client calls POST /api/v2/auth/exchange with that JWT and receives a short-lived MarkUp token.
  3. Use the exchange token as Authorization: Bearer <EXCHANGE-TOKEN> for feedback-related endpoints (threads, messages, markups read).

See the Authentication resource for the full endpoint reference (config and exchange).

Feedback routes with API keys

Feedback routes (threads, messages, markup status / read-only / reviews) also accept a workspace- or organization-scoped API key as a Bearer token. Use this for automated or admin server-to-server posts where there is no end user to attribute to.

  • Authorization is bounded to the key’s scope: workspace keys can only access markups in their workspace; organization keys can only access markups in workspaces belonging to their organization. Anything outside scope returns 403.
  • New threads and messages created with an API key are attributed to the API key’s owner identity (a user record of type api) — not to a human end user. Use exchange tokens when you need attribution to the real commenter.
  • Required scopes: threads:read for read endpoints, threads:write for write endpoints. These are configured when the API key is created.
Curl - List threads using an API key
curl "https://api.markup.io/api/v2/threads?markupId=<MARKUP-ID>" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
APIVersioning