Authentication

The /v1 API uses one auth model: a workspace API key sent as a Bearer token. Each key belongs to exactly one workspace and can only reach that workspace.

Surface	Auth
`/v1/*` REST API, the SDK, `@neuraldraft/mcp`	API key (`Authorization: Bearer ndsk_live_…`)
Hosted connector `https://neuraldraft.io/mcp` (Claude, ChatGPT, Codex, Claude Code, Cursor)	Sign-in with Google or an emailed code (OAuth). No key.
`nd.js` blocks and `/_nd/api/*` on a site	None. Public site data only, keyed by the site address. See Embeds and CORS.
`/v1/public/*`, `/v1/contact-forms` (POST), `/v1/newsletters/subscribe`	None (tenant from `?project_id=`), rate limited per IP.

Key format

ndsk_live_2NgcaXxFqLPo7K3vR8zHwT

ndsk_live_ followed by a random secret. We store only a hash, so a lost key cannot be recovered: create a new one.

Creating a key

Open the admin

app.neuraldraft.io → Settings → For developers → API keys.

Create key

Name it after where it lives (vercel-prod, claude-code-laptop). Pick full access or individual scopes.

Copy it once

Put it in your secret manager or .env (never in browser code or git).

You can also manage keys with the API: GET/POST /v1/projects/me/api-keys and DELETE /v1/projects/me/api-keys/{id}.

Sending the key

curl https://api.neuraldraft.io/v1/projects/me \
  -H "Authorization: Bearer $NEURALDRAFT_API_KEY"

import { NeuralDraftClient } from "@neuraldraft/sdk";
const nd = new NeuralDraftClient({ apiKey: process.env.NEURALDRAFT_API_KEY! });
// or: const nd = NeuralDraftClient.fromEnv();  // reads NEURALDRAFT_API_KEY

import os, httpx
r = httpx.get("https://api.neuraldraft.io/v1/projects/me",
              headers={"Authorization": f"Bearer {os.environ['NEURALDRAFT_API_KEY']}"})

Scopes

A key has * (full access) or a list of scopes. blog:* grants every blog: scope.

Scope	Covers
`brand:read` / `brand:write`	`GET` / `PATCH /v1/brand`
`content:read` / `content:write`	`/v1/content` (site texts, translation keys)
`components:read` / `components:write`	`/v1/components`
`pages:read` / `pages:write`	`/v1/pages`
`galleries:read` / `galleries:write`	`/v1/galleries`
`images:read` / `images:write`	`/v1/images`
`blog:read` / `blog:write` / `blog:publish`	`/v1/blog-posts`, categories, tags; publishing
`social:read` / `social:write` / `social:publish`	`/v1/social-posts`, `/v1/social-accounts`
`booking:read` / `booking:write` / `booking:confirm` / `booking:cancel`	services, availability, settings, bookings
`commerce:read` / `commerce:write`	products, variants, categories
`orders:read` / `orders:write` / `orders:refund`	`/v1/orders`
`forms:read` / `forms:write`	`/v1/newsletters`, `/v1/contact-forms` (admin list/delete)
`jobs:read` / `jobs:cancel`	`/v1/jobs`
`webhooks:read` / `webhooks:write`	`/v1/webhook-endpoints`, `/v1/webhook-deliveries`

A missing scope returns 403:

{
  "type": "https://neuraldraft.com/errors/insufficient-scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the required scope: commerce:write.",
  "code": "insufficient_scope",
  "required_scope": "commerce:write"
}

Auth errors

Status	`code`	When
`401`	`missing_api_key`	No `Authorization` header.
`401`	`invalid_api_key`, `revoked_api_key`, `expired_api_key`	Unknown, revoked or expired key.
`403`	`insufficient_scope`	Valid key without the scope.
`403`	`project_not_provisioned`	The workspace isn’t ready yet.

See Errors for the rest.

Revoking and rotating

Revoke a key in the admin or with DELETE /v1/projects/me/api-keys/{id}; it stops working right away. To rotate, create the new key, deploy it, then revoke the old one: a workspace can hold several active keys.

Several workspaces (agencies)

A key never reaches another workspace. To work across clients, hold one key per client: NEURALDRAFT_API_KEYS in the developer MCP or NeuralDraftWorkspaces in the SDK.

Get started

Build with AI

Sites

Agencies

Features

SDK and API

Snippets

Key format

Creating a key

Sending the key

Scopes

Auth errors

Revoking and rotating

Several workspaces (agencies)

​Key format

​Creating a key

​Sending the key

​Scopes

​Auth errors

​Revoking and rotating

​Several workspaces (agencies)

Key format

Creating a key

Sending the key

Scopes

Auth errors

Revoking and rotating

Several workspaces (agencies)