Authentication

The MASK API uses API keys to authenticate requests. Each key is scoped to a workspace and can be restricted to specific permissions. All requests must include a valid API key in the Authorization header.

API Keys

API keys are created from your workspace settings. Navigate to Settings → API Keys → Create Key. Every key belongs to a single workspace and can only access resources within that workspace.

A key is the prefix mk_ followed by 64 hexadecimal characters. There is one environment: every key creates real links and records real analytics, so anything you send while developing lands in the workspace the key belongs to. There is no test mode and no sandbox key.

To keep development away from production data, create a separate workspace for it and mint a key there.

The API is a paid feature. A key only works while its workspace is on Growth or above; if the workspace drops to Hobby, existing keys stop authenticating and return 401 Unauthorized.

Creating API Keys

To create an API key:

1. Go to your workspace Settings → API Keys.
2. Click Create Key.
3. Enter a descriptive name (e.g. "Production Backend" or "CI Pipeline").
4. Select the scopes your integration requires.
5. Click Create. The full key is displayed once — copy it immediately.

The key value is only shown at creation time. If you lose it, you must create a new key.

Scopes

Each API key is assigned one or more scopes that control what operations it can perform. Follow the principle of least privilege: only grant the scopes your integration needs.

Fourteen scopes exist, and this is all of them. Several are reserved: they can be granted to a key, but no endpoint on /api/v1 requires them today, so granting one adds nothing. The Reserved column says which.

If a request requires a scope that the API key does not have, the API returns 403 Forbidden. The body is a single error string. The links and QR endpoints return it unadorned; the conversions and goals endpoints name the scope they wanted.

{
  "error": "Insufficient scope"
}

{
  "error": "Insufficient scope. This endpoint requires \"conversions:read\"."
}

Bearer Token Usage

Include your API key in the Authorization header using the Bearer scheme. The key must be sent with every request.

curl https://mask.pk/api/v1/links \
  -H "Authorization: Bearer mk_3f9a1c7e5b208d46a1f0c93e78b25d4610fa8c3729de154bb06e7a9f2c8d3510"

const response = await fetch("https://mask.pk/api/v1/links", {
  headers: {
    Authorization: `Bearer ${process.env.MASK_API_KEY}`,
    "Content-Type": "application/json",
  },
});

const { data } = await response.json();

import os
import requests

response = requests.get(
    "https://mask.pk/api/v1/links",
    headers={"Authorization": f"Bearer {os.environ['MASK_API_KEY']}"},
)

data = response.json()["data"]

Requests without a valid API key receive a 401 Unauthorized response. The same body is returned whether the key is missing, malformed, revoked, expired, or belongs to a workspace that is no longer on a paid plan.

{
  "error": "Unauthorized"
}

Key Rotation

To rotate a key without downtime, follow this procedure:

1. Create a new API key with the same scopes as the existing key.
2. Update your application to use the new key.
3. Deploy the change and verify requests succeed with the new key.
4. Revoke the old key from Settings → API Keys.

Once a key is revoked, all requests using that key immediately return 401 Unauthorized. Revocation is irreversible.

Nothing expires or disables a key on its own. Each key shows when it was last used, so you can spot keys nothing is calling any more, but reviewing and revoking them is a manual step.

Security Best Practices

# .env (add to .gitignore)
MASK_API_KEY=mk_3f9a1c7e5b208d46a1f0c93e78b25d4610fa8c3729de154bb06e7a9f2c8d3510

# Usage in Node.js
const apiKey = process.env.MASK_API_KEY;