API Keys & CI/CD

Pro and Enterprise only.

Overview

API keys let you authenticate with Mockra from CI/CD pipelines, scripts, and automated tools — without using your personal Auth0 session. Combined with ephemeral namespaces, you can spin up an isolated mock environment for each test run and tear it down when done.

---

Creating an API key

1. Open the API Keys section in your workspace dashboard
2. Click Create API key
3. Give it a name (e.g. "GitHub Actions")
4. Choose the scopes the key needs (see Scopes below)
5. Copy the key immediately — it is shown only once

API keys look like:

mra_a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

The prefix mra_ identifies it as a Mockra API key. The remaining 64 characters are a random hex string.

---

Using an API key

Include the key in the Authorization header of any request to api.mockra.io:

curl https://api.mockra.io/workspaces \
  -H "Authorization: Bearer mra_a3f9b2c1..."

---

Scopes

Every API key is created with one or more scopes that limit what it can do. Scopes are set at creation time and cannot be changed afterward.

Scope	What it allows
mock:read	Read mock configs and call mock endpoints (always included)
workspace:read	Read workspace details, schemas, billing state
workspace:write	Create/update/delete schemas, mock configs, state configs, and namespaces

For read-only CI keys (e.g. a key used only to read mock URLs during a build): deselect workspace:write. This limits blast radius if the key is ever leaked.

For full CI/CD keys (e.g. a key that creates ephemeral namespaces and configures mocks): select all three scopes.

The mock:read scope is always included and cannot be removed.

---

Revoking an API key

In the dashboard, click Revoke next to any key. The key stops working immediately. Revocation is permanent — you cannot re-enable a revoked key.

---

Ephemeral namespaces

An ephemeral namespace is a temporary mock environment with its own namespace slug. Use one per test run for complete isolation — no shared state between parallel test runs.

Create a namespace

curl -X POST https://api.mockra.io/namespaces \
  -H "Authorization: Bearer mra_..." \
  -H "Content-Type: application/json"

Response:

{
  "namespace": "amber-river-7f3a",
  "mock_base_url": "https://mock.mockra.io/amber-river-7f3a"
}

The namespace slug is randomly generated and unique.

Use the namespace in tests

Your mock endpoints are live immediately at the returned URL:

curl https://mock.mockra.io/amber-river-7f3a/users

The namespace inherits the mock configs from your workspace — all endpoints defined in your schemas are available.

Delete the namespace

When the test run is complete, delete the namespace to clean up:

curl -X DELETE https://api.mockra.io/namespaces/amber-river-7f3a \
  -H "Authorization: Bearer mra_..."

This removes all KV cache entries for the namespace and deletes the namespace record. The deletion cascades — any state stored in the namespace's Durable Object is also cleared.

---

GitHub Actions example

name: Integration tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create ephemeral mock namespace
        id: mock
        run: |
          RESPONSE=$(curl -s -X POST https://api.mockra.io/namespaces \
            -H "Authorization: Bearer ${{ secrets.MOCKRA_API_KEY }}")
          NAMESPACE=$(echo $RESPONSE | jq -r '.namespace')
          MOCK_URL=$(echo $RESPONSE | jq -r '.mock_base_url')
          echo "namespace=$NAMESPACE" >> $GITHUB_OUTPUT
          echo "mock_url=$MOCK_URL" >> $GITHUB_OUTPUT

      - name: Run integration tests
        env:
          API_BASE_URL: ${{ steps.mock.outputs.mock_url }}
        run: npm test

      - name: Delete mock namespace
        if: always()
        run: |
          curl -s -X DELETE \
            https://api.mockra.io/namespaces/${{ steps.mock.outputs.namespace }} \
            -H "Authorization: Bearer ${{ secrets.MOCKRA_API_KEY }}"

Add your API key as a repository secret named MOCKRA_API_KEY in GitHub → Settings → Secrets.

---

k6 example with API key

import http from "k6/http";
import { check } from "k6";

const MOCK_BASE = __ENV.MOCK_BASE_URL || "https://mock.mockra.io/your-namespace";

export const options = {
  vus: 100,
  duration: "30s",
};

export default function () {
  const res = http.get(`${MOCK_BASE}/users`);
  check(res, {
    "status 200": (r) => r.status === 200,
    "has users": (r) => JSON.parse(r.body).length > 0,
  });
}

Run with:

k6 run --env MOCK_BASE_URL=https://mock.mockra.io/amber-river-7f3a script.js

---

State isolation between runs

Ephemeral namespaces have their own Durable Object for stateful mock state. When you delete the namespace, all state is cleared. This means:

• Parallel test runs don't interfere with each other
• You never need to manually reset state between runs
• Each run starts fresh with step 1 of every state sequence

For more on stateful mocks, see Stateful Mocks.