Authentication

All requests to the Program API (except health checks) require a Bearer token. For scripts, backends, and CI, use a workspace API key. Browser sessions in the web app authenticate separately through Questra Auth. Claude and other MCP clients use user OAuth, not API keys. API keys are scoped to the workspace that created them. You do not send an organization or workspace header — the key selects the tenant.

Create an API key

You need the api_keys:write permission (workspace owner or admin). Members can view keys but cannot create them.

Open the web app

Go to API keys

Open Settings → API keys.

Create a key

Click Create key. Give it a name you will recognize later (for example Production backend).

Choose scopes

Pick the permissions this key should have. * grants full Program API access for the workspace. For a read-only integration, surveys:read and meta:read are enough to list surveys and call GET /v1/whoami.

Copy the secret

The full key is shown once, prefixed qpk_live_. Store it in a secret manager or environment variable. List and get responses only include a key_hint (last four characters).

Treat the secret like a password. Do not commit it to source control or log it. If it leaks, rotate or delete the key immediately.

You can also create keys with POST /v1/api_keys if you already have a key (or a session) that includes api_keys:write. The create response includes data.key once — same as the dashboard.

Use the key

Pass the secret in the Authorization header on every request.

curl https://api.program.questra.ai/v1/whoami \
  -H "Authorization: Bearer $QUESTRA_API_KEY"

const response = await fetch('https://api.program.questra.ai/v1/whoami', {
  headers: {
    Authorization: `Bearer ${process.env.QUESTRA_API_KEY}`,
  },
});

import os
import requests

response = requests.get(
    'https://api.program.questra.ai/v1/whoami',
    headers={'Authorization': f'Bearer {os.environ["QUESTRA_API_KEY"]}'},
)

A successful GET /v1/whoami returns the key’s workspace and auth_method: "api_key":

{
  "service": "questra-program",
  "workspace_id": "org_...",
  "subject": "apikey:...",
  "auth_method": "api_key",
  "permissions": ["*"]
}

Invalid, disabled, or expired keys return 401. A valid key that lacks a required permission returns 403.

Base URLs

Environment	Base URL
Production	`https://api.program.questra.ai`
Staging	`https://api.program.staging.questra.ai`

All documented endpoints live under /v1. Health (GET /health) is unauthenticated and sits outside /v1.

Scopes

Each key stores an explicit list of scopes. The API checks them before the handler runs. resource:write also satisfies resource:read. * satisfies every permission.

Scope	Typical use
`*`	Full workspace access
`surveys:read` / `surveys:write`	Surveys, files, questionnaires, programming, content
`surveys:share`	Sharing surveys with collaborators
`integrations:read` / `integrations:write`	Platform connections and upstream surveys
`webhooks:read` / `webhooks:write`	Endpoints, events, and deliveries
`workflows:read` / `workflows:write`	Workflow status and streams
`api_keys:read` / `api_keys:write`	Manage other keys
`meta:read`	Workspace identity and other meta reads (whoami itself accepts any valid key)

Create requests require a non-empty scopes array — there is no implicit full-access default unless you pass *.

Manage keys

From Settings → API keys, or the API keys resource:

Disable — PATCH /v1/api_keys/{apiKeyId} with { "enabled": false }. The key stops working without deleting the record.
Rotate — POST /v1/api_keys/{apiKeyId}/rotate issues a new qpk_live_… secret and invalidates the old one. Scopes stay the same. Copy the new secret immediately.
Delete — DELETE /v1/api_keys/{apiKeyId} revokes the key permanently.

Optional expires_at on create or update sets an expiry. Omit or null for a key that does not expire.

Environment variables

export QUESTRA_API_KEY=qpk_live_...

const apiKey = process.env.QUESTRA_API_KEY;

Next: Quickstart to list surveys with that key.

Getting started

Workflows

Webhooks

Create an API key

Use the key

Base URLs

Scopes

Manage keys

Environment variables

​Create an API key

​Use the key

​Base URLs

​Scopes

​Manage keys

​Environment variables

Create an API key

Use the key

Base URLs

Scopes

Manage keys

Environment variables