Authentication

Every endpoint except GET /v1/status and the public feedback URL (POST /v1/feedback/{organizationSlug}) requires a bearer credential in the Authorization header. The API accepts two kinds of credential and checks both against the same scopes:

Credential	Looks like	Best for
API key	`ntra_...`, created on the API Keys page	Scripts, backends, CI and any manual setup where you paste a secret once
OAuth access token	A JWT issued by the Notra authorization server	CLIs, MCP clients and agents that sign a user in, get a token for that user’s organization and refresh it without storing a long-lived secret

The API tells the two apart by shape, verifying a value that parses as a JWT as an OAuth token and anything else as an API key.

How it works

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/posts"

const response = await fetch("https://api.usenotra.com/v1/posts", {
  headers: {
    Authorization: `Bearer ${process.env.NOTRA_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);

import { Notra } from "@usenotra/sdk";

const notra = new Notra({
  bearerAuth: process.env.NOTRA_API_KEY ?? "",
});

const result = await notra.content.listPosts();
console.log(result);

The header format is Authorization: Bearer <credential>, and the scheme name is case-insensitive. Keys created in the dashboard start with ntra_, and OAuth access tokens go in the same header, as described in OAuth.

The SDK reads the key from the bearerAuth option. Its generated README refers to a NOTRA_BEARER_AUTH environment variable, but any variable name works as long as you pass the value in.

Create an API key

Open the API Keys page

In the dashboard, click API Keys at the bottom of the sidebar (app.usenotra.com/{org-slug}/api-keys). Keys belong to the organization you are viewing.

Start from a preset or a blank key

The page offers three presets: MCP Server (read and write on every resource), SDK (read on every resource) and CLI (read and write on every resource), and each one prefills a name and permissions. Create API Key opens the same form with read access on every resource.

Choose a name, expiration and permissions

Expiration is one of No expiry, 7 days, 30 days, 60 days or 90 days. Permissions use one of three access modes: Full Access (every scope), GEO Access (read and write on the GEO resources only) or Restricted, which shows a None / Read / Write selector for each resource.

Copy the key

The dashboard shows the key once, right after creation, so store it server-side. Later you can rename a key, change its expiration or adjust its permissions from the same page, and you can delete it at any time.

Scopes

Every resource has a <resource>.read and a <resource>.write scope. The API derives the required scope from the request: GET needs the read scope, and POST, PUT, PATCH and DELETE need the write scope. A write scope does not imply the read scope, so a key that should both read and update posts needs posts.read and posts.write. In the dashboard, choosing Write for a resource grants both.

Resource	Scopes	Covers
Webhooks	`webhooks.read`, `webhooks.write`	`/v1/webhooks`, including delivery history and retry
Posts	`posts.read`, `posts.write`	`/v1/posts`, including generation jobs
Brand identities	`brand-identities.read`, `brand-identities.write`	`/v1/brand-identities`
Integrations	`integrations.read`, `integrations.write`	`/v1/integrations`
Schedules	`schedules.read`, `schedules.write`	`/v1/schedules`
Event triggers	`event-triggers.read`, `event-triggers.write`	`/v1/event-triggers`
Chats	`chats.read`, `chats.write`	`/v1/chats`, `/v2/agent-chats`, `/v2/eve`
Skills	`skills.read`, `skills.write`	`/v1/skills`
Agent feedback	`feedback.read`, `feedback.write`	`/v1/feedback` (except the public submit URL)
Projects	`projects.read`, `projects.write`	`/v1/projects` and `/v1/projects/{projectId}`
GEO settings	`geo-settings.read`, `geo-settings.write`	`/v1/projects/{projectId}/geo/settings`
GEO prompts	`prompts.read`, `prompts.write`	`.../geo/prompts`, `.../geo/sequences`
GEO competitors	`competitors.read`, `competitors.write`	`.../geo/competitors`
GEO scans	`scans.read`, `scans.write`	`.../geo/scans`
GEO visibility	`visibility.read`, `visibility.write`	`.../geo/visibility`
GEO content briefs	`briefs.read`, `briefs.write`	`.../geo/gaps`, `.../geo/briefs`
GEO agent readiness	`agent-readiness.read`, `agent-readiness.write`	`.../geo/agent-readiness`
GEO AI traffic	`traffic.read`, `traffic.write`	`.../geo/traffic`, `/v1/geo/ingest`

GET /v1/status and POST /v1/feedback/{organizationSlug} need no key at all.

Legacy scopes

Keys created before granular scopes existed carry api.read or api.write, and they keep working. api.write satisfies every scope and api.read satisfies every read scope. The API Keys page shows these keys with their expanded permissions, and saving a key from the editor converts it to granular scopes.

Plan requirements

The API checks scopes first, then the organization’s plan:

POST, PUT and PATCH requests need an active paid plan or a positive AI credit balance, and otherwise the API returns 402 with error: "Active subscription required". GET and DELETE always work so you can read and remove your data.
Every GEO endpoint (/v1/projects/* and /v1/geo/ingest/*), reads included, needs a GEO plan, and otherwise the API returns 402 with error: "GEO requires a Starter, Growth, or Scale plan".

OAuth

OAuth lets a CLI, MCP client or agent get a token for a signed-in user without that user creating and pasting an API key. The Notra authorization server at https://oauth.usenotra.com issues the tokens. Each token is bound to one organization and carries the scopes the user approved, and you can refresh and revoke tokens. The Notra MCP server at https://mcp.usenotra.com/mcp accepts the same tokens. Use OAuth when a person is present to approve access, when you want per-user identity on requests or when the credential should expire on its own, and use an API key for unattended server-to-server work.

Discovery

Notra publishes everything a client needs as standard metadata:

Document	URL
Protected resource metadata (API)	`https://api.usenotra.com/.well-known/oauth-protected-resource`
Protected resource metadata (MCP)	`https://mcp.usenotra.com/.well-known/oauth-protected-resource`
Authorization server metadata	`https://api.usenotra.com/.well-known/oauth-authorization-server`
Human and agent readable guide	`https://www.usenotra.com/auth.md`

The protected resource metadata lists the authorization server, scopes_supported (openid and offline_access) and bearer_methods_supported: ["header"]. Any 401 from the API or the MCP server carries WWW-Authenticate: Bearer resource_metadata="..." with the URL of the matching document, so a client that starts with an unauthenticated request can discover the rest from there. The authorization server exposes:

Endpoint	URL
Authorization	`https://oauth.usenotra.com/oauth2/authorize`
Token	`https://oauth.usenotra.com/oauth2/token`
Dynamic client registration	`https://oauth.usenotra.com/oauth2/register`
Device authorization	`https://oauth.usenotra.com/oauth2/device_authorization`
Revocation	`https://oauth.usenotra.com/oauth2/revoke`
JWKS	`https://oauth.usenotra.com/oauth2/jwks`

The server supports the authorization code grant with PKCE (S256), the refresh token grant and the device authorization grant. Clients are public (token_endpoint_auth_methods_supported: ["none"]), so no client secret is involved.

Register a client

curl -X POST https://oauth.usenotra.com/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme CLI",
    "redirect_uris": ["http://127.0.0.1:8765/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'

Request openid, and add offline_access if you want refresh tokens. WorkOS does not allow custom OAuth scopes on dynamically registered clients, including ChatGPT CIMD clients. Instead, the consent screen asks the user to select a workspace and one access level: Read only, Write only or Full access for all resources in the scope table. Notra signs these choices into access-token claims and maps them to the same granular permissions as API keys. Read only grants every read scope, Write only grants every write scope and Full access grants both. Missing choices grant no access, broader role permissions cannot override these choices and the API checks current workspace membership on every request.

Authorization code flow with PKCE

Generate a random code_verifier and its S256 code_challenge.
Open the user’s browser at the authorization endpoint:

https://oauth.usenotra.com/oauth2/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http://127.0.0.1:8765/callback
  &scope=openid%20offline_access
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE

The user signs in, picks the workspace and approves an access level, and the browser then redirects to redirect_uri with code and state.
Exchange the code for tokens:

curl -X POST https://oauth.usenotra.com/oauth2/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d code=THE_CODE \
  -d redirect_uri=http://127.0.0.1:8765/callback \
  -d code_verifier=YOUR_CODE_VERIFIER

The response contains access_token, expires_in, token_type: "Bearer", the granted scope and, when the user granted offline_access, refresh_token.

Device flow for headless CLIs

When there is no browser on the machine (SSH sessions, containers, CI runners with a person watching), use the device authorization grant:

curl -X POST https://oauth.usenotra.com/oauth2/device_authorization \
  -d client_id=YOUR_CLIENT_ID \
  -d scope="openid offline_access"

Show the returned verification_uri and user_code to the user, then poll the token endpoint at the returned interval until they approve:

curl -X POST https://oauth.usenotra.com/oauth2/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=YOUR_CLIENT_ID \
  -d device_code=THE_DEVICE_CODE

Until the user finishes, the token endpoint answers with error: "authorization_pending" or slow_down, so keep polling. After approval, you get the same token response as the code flow.

Use the access token

Send it exactly like an API key:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://api.usenotra.com/v1/posts"

The API reads the organization from the token, so you pass nothing else. Access tokens are short-lived, so when a request returns 401 with an expiry error, refresh and retry. For OAuth tokens, per-key rate limits apply per user and organization, so two users in the same organization have separate budgets.

Refresh with offline_access

If the user granted offline_access, exchange the refresh token for a new access token when the old one expires:

curl -X POST https://oauth.usenotra.com/oauth2/token \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d refresh_token=YOUR_REFRESH_TOKEN

Without offline_access, there is no refresh token and the user must sign in again when the access token expires.

Revocation

Revoke a token when the user signs out or the client is uninstalled:

curl -X POST https://oauth.usenotra.com/oauth2/revoke \
  -d client_id=YOUR_CLIENT_ID \
  -d token=YOUR_REFRESH_TOKEN

Discard revoked tokens immediately. If a later request returns 401, run discovery and the authorization flow again instead of retrying with the old token.

OAuth-specific errors

OAuth tokens go through the same { error, code, recovery } envelope. Besides the errors under Error responses, you may see:

Status	`error`	Meaning
`401`	`ERR_JWT_EXPIRED` and other `ERR_JWT_` / `ERR_JWS_` codes	The token failed signature, issuer or expiry validation. Refresh or re-authorize.
`401`	`Missing token audience` / `Invalid token audience`	The token was not issued for `https://api.usenotra.com` or the MCP server. Request one for the right resource.
`401`	`Missing OAuth organization`	The token is not bound to an organization. Complete the flow again and choose an organization.
`401`	`No local user found for OAuth subject` / `No local organization found for OAuth token`	The signed-in user or organization has no Notra account yet. Sign up in the dashboard first.
`503`	`OAuth verification unavailable`	Signing keys could not be fetched. Retry with exponential backoff.

Error responses

Authentication and authorization failures return a JSON body with three fields, for API keys and OAuth tokens alike.

{
  "error": "Forbidden",
  "code": "FORBIDDEN",
  "recovery": "Request a key with the required scope for this endpoint, then retry after verifying whether the previous mutation completed."
}

Status	`error`	Meaning
`401`	`Missing API key`	No `Authorization` header, or no token after `Bearer`.
`401`	`Invalid API key`	The key is unknown, disabled or expired.
`403`	`Forbidden`	The key is valid but lacks the scope for this method and path.
`403`	`Forbidden: API key must be scoped to an organization`	The key is not attached to an organization. Create a new key from the dashboard.
`429`	`API key rate limit exceeded`	The key itself is throttled, which is separate from the per-endpoint limits in Rate Limits.
`503`	`Service unavailable`	The key could not be verified. Retry with exponential backoff.

code is the error string upper-cased with non-alphanumeric runs replaced by _. 401 responses also include WWW-Authenticate: Bearer resource_metadata="https://api.usenotra.com/.well-known/oauth-protected-resource", which is the entry point for OAuth discovery.

const response = await fetch("https://api.usenotra.com/v1/posts", {
  headers: { Authorization: `Bearer ${process.env.NOTRA_API_KEY}` },
});

if (!response.ok) {
  const body = await response.json();
  console.error(response.status, body.error, body.code);
}

import { Notra } from "@usenotra/sdk";
import * as errors from "@usenotra/sdk/models/errors";

const notra = new Notra({
  bearerAuth: process.env.NOTRA_API_KEY ?? "",
});

try {
  const result = await notra.content.listPosts();
  console.log(result);
} catch (error) {
  if (error instanceof errors.NotraError) {
    console.log(error.message);
    console.log(error.statusCode);
    console.log(error.body);
  }
}

Security best practices

Treat API keys as secrets. Do not expose them in client-side code, public repositories or logs.

Grant the smallest set of scopes a workflow needs and set an expiration on keys used in CI or short-lived scripts. Create one key per integration so you can revoke it without affecting anything else.

If a key is exposed, delete it from the API Keys page, where deletion takes effect immediately. For OAuth tokens, call the revocation endpoint.

Getting Started

Developer Tools

Guides

Webhooks

Endpoints

How it works

Create an API key

Scopes

Legacy scopes

Plan requirements

OAuth

Discovery

Register a client

Authorization code flow with PKCE

Device flow for headless CLIs

Use the access token

Refresh with offline_access

Revocation

OAuth-specific errors

Error responses

Security best practices

​How it works

​Create an API key

​Scopes

​Legacy scopes

​Plan requirements

​OAuth

​Discovery

​Register a client

​Authorization code flow with PKCE

​Device flow for headless CLIs

​Use the access token

​Refresh with offline_access

​Revocation

​OAuth-specific errors

​Error responses

​Security best practices

How it works

Create an API key

Scopes

Legacy scopes

Plan requirements

OAuth

Discovery

Register a client

Authorization code flow with PKCE

Device flow for headless CLIs

Use the access token

Refresh with offline_access

Revocation

OAuth-specific errors

Error responses

Security best practices