API Keys

Overview

API keys authenticate your requests to Roark’s API, enabling secure access to monitoring, testing, and analytics features.

API keys are essential for all integrations - whether you’re using our SDKs, webhooks, or direct API calls.

Two kinds of credential

Roark issues two shapes of bearer credential. Both go in the same Authorization: Bearer header, and most callers only ever need the first.

	Project key	User credential
Created by	Settings → API keys in the dashboard	approving a browser consent (`roark auth login`, MCP connector)
Belongs to	one project, permanently	you, within one organization
Names its project	implicitly: the key is the project	per request, with the `X-Roark-Project-Id` header
Access	exactly the scopes and permissions chosen at creation	the permissions you approved, narrowed to your role on each project
Revoked at	Settings → API keys	Settings → Account → Connected apps
Survives you leaving	yes, it belongs to the project	no, deactivating your account revokes it
Right for CI	yes	no, it is tied to a person

Use a project key for anything automated: ingestion, webhooks, CI pipelines, a service that outlives whoever set it up. A project key keeps working when people join and leave, which is exactly what a pipeline needs and exactly what a user credential deliberately does not do.

A user credential cannot exceed the person holding it. Its access is recomputed on every request as the permissions approved at consent intersected with your live membership of the project being acted on, so losing access in the dashboard removes it from the credential at the same moment.

Generating an API Key

Navigate to API Keys

Go to the API Keys section in your dashboard

Create New Key

Click the “Create API Key” button

Set Permissions

Choose your access level:

Read-Only: Retrieve data only
Full Access: Read and write operations

Save Securely

Copy and store your key immediately - it won’t be shown again

Using Your API Key

All API requests require authentication via the Authorization header:

curl -X GET "https://api.roark.ai/health" \
     -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get("https://api.roark.ai/health", headers=headers)

const response = await fetch("https://api.roark.ai/health", {
  headers: {
    "Authorization": `Bearer YOUR_API_KEY`
  }
});

const axios = require('axios');

const config = {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};

const response = await axios.get('https://api.roark.ai/health', config);

Choosing the project a request acts on

A project key is bound to one project, so it never has to say which. A user credential can reach every project you are a member of, so each request names one with the X-Roark-Project-Id header:

curl -X GET "https://api.roark.ai/v1/agent" \
     -H "Authorization: Bearer YOUR_CREDENTIAL" \
     -H "X-Roark-Project-Id: 0b2b1f9e-5f1a-4c7e-9c3d-1f2e3a4b5c6d"

Two endpoints answer “what am I holding, and what can it reach”, so a client never has to infer either from a failed request:

curl -X GET "https://api.roark.ai/v1/me" \
     -H "Authorization: Bearer YOUR_CREDENTIAL"

{
  "data": {
    "tokenScope": "USER",
    "user": { "id": "…", "email": "you@example.com", "name": "You" },
    "organization": { "id": "…", "name": "Acme" },
    "defaultProject": { "id": "…", "name": "Support line", "slug": "support-line" },
    "grantedPermissions": ["call:read", "call:create", "metric:read"],
    "scopes": ["WRITE"]
  }
}

curl -X GET "https://api.roark.ai/v1/projects" \
     -H "Authorization: Bearer YOUR_CREDENTIAL"

{
  "data": {
    "projects": [
      {
        "id": "0b2b1f9e-5f1a-4c7e-9c3d-1f2e3a4b5c6d",
        "name": "Support line",
        "slug": "support-line",
        "organization": { "id": "…", "name": "Acme" },
        "grantedPermissions": ["call:read", "metric:read"]
      }
    ]
  }
}

GET /v1/projects is computed through the same permission engine that gates every other request, so it will not advertise a project that your next call rejects. A project key gets a one-element list: the project it is bound to.

When a project cannot be resolved

Status	Meaning	What to do
400	a user credential named no project, and has no default to fall back on	send `X-Roark-Project-Id`; `GET /v1/projects` lists valid ids
403	the project is outside the credential’s organization, or you are not an active member of it	pick one from `GET /v1/projects`
403	a project key sent a header naming a different project than its own	drop the header, or use a credential for that project

That last one is deliberately an error rather than a silent no-op. A caller that believes it is writing to project B must never end up writing to project A.

A user credential created through a browser consent remembers the project chosen on the consent screen and falls back to it when a request names none, so a client that never sends the header still works. Do not rely on it if your integration touches more than one project: send the header explicitly and the behaviour stays obvious.

Only relevant if you wrote your own client against POST /v1/cli/auth/token. The Roark CLI and MCP server already handle this. That endpoint’s response gained fields, and projectId is now nullable:

{
  "token": "roark…",
  "name": "CLI on my-laptop",
  "scopeKind": "USER",
  "projectId": null,
  "organizationId": "…",
  "defaultProjectId": "…"
}

Read scopeKind to know what you were given. A projectId of null means the credential is user-scoped and has no single project: treat it as “call GET /v1/projects and pick one”, never as an error. defaultProjectId is the project chosen on the consent screen, which is what the API falls back to when a request names none, so storing it is the simplest way to keep working without asking.

A client that validates projectId as a required string will reject a perfectly good user credential. Accept both shapes before anyone in your organization is issued one.

Security Best Practices

Never expose your API key in client-side code, public repositories, or logs. If compromised, regenerate immediately in your dashboard.

Environment Variables

Store keys in .env files or secure vaults, never hardcode them

Regular Rotation

Regenerate keys periodically to maintain security

Least Privilege

Use read-only keys when write access isn’t needed

Monitor Usage

Check last-used timestamps to detect unauthorized access

Common Integration Patterns

SDK Integration
CI/CD Pipeline

Initialize SDKs with your key:

const roark = new RoarkClient({
  apiKey: process.env.ROARK_API_KEY
});

Store as secret in your pipeline:

env:
  ROARK_API_KEY: ${{ secrets.ROARK_API_KEY }}

Getting Started

Simulations

Observability

Metrics

Config as Code

Autoimprove

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Overview

Two kinds of credential

Generating an API Key

Using Your API Key

Choosing the project a request acts on

When a project cannot be resolved

Security Best Practices

Environment Variables

Regular Rotation

Least Privilege

Monitor Usage

Common Integration Patterns

Need Help?

API Reference

Integration Guides

​Overview

​Two kinds of credential

​Generating an API Key

​Using Your API Key

​Choosing the project a request acts on

​When a project cannot be resolved

​Building your own browser login

​Security Best Practices

Environment Variables

Regular Rotation

Least Privilege

Monitor Usage

​Common Integration Patterns

​Need Help?

API Reference

Integration Guides

Overview

Two kinds of credential

Generating an API Key

Using Your API Key

Choosing the project a request acts on

When a project cannot be resolved

Building your own browser login

Security Best Practices

Common Integration Patterns

Need Help?