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.

Keys use a prefix to indicate the environment:

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.

If a request requires a scope that the API key does not have, the API returns 403 Forbidden with the required scope in the error body.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the required scope.",
    "required_scope": "links:write"
  }
}

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_live_abc123def456"

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

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

import requests

response = requests.get(
    "https://mask.pk/api/v1/links",
    headers={"Authorization": "Bearer mk_live_abc123def456"},
)

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

Requests without a valid API key receive a 401 Unauthorized response.

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Include a valid key in the Authorization header."
  }
}

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.

Keys that have not been used in 90 days are flagged as inactive in the dashboard. We recommend revoking inactive keys regularly.

Security Best Practices

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

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