Get started

Authentication

Every request carries an API key as a bearer token. A key acts as the person who created it, limited to the scopes it was given.

API keys

Keys are created in the app, under Settings → Developers → API keys → Create key. Give each one a name that says where it is used, and choose its permissions. The key is shown once, when it is created; afterwards the app shows only its beginning, sk_live_ and eight characters.

Format	`sk_live_` followed by 64 hexadecimal characters.
Owner	The person who created it. The key has that person’s permissions — never more.
Scopes	The permissions chosen at creation. They cannot be changed later; create a new key instead.
Lifetime	Until it is revoked, or until its expiry date when it has one.

Making authenticated requests

Send the key in the Authorization header of every request:

Header

Authorization: Bearer sk_live_…

List users

curl -G https://acme.nextora.co/api/v1/users \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d limit=1

Response200 OK

{
  "data": [
    {
      "id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
      "full_name": "Maya Chen",
      "email": "[email protected]",
      "role": "admin",
      "avatar_url": null,
      "is_active": true
    }
  ],
  "meta": {
    "limit": 1,
    "has_more": true,
    "next_cursor": "eyJpZCI6IjNmMWM5YTdlIiwiY3JlYXRlZF9hdCI6IjIwMjYtMDktMTRUMDk6MzA6MDBaIn0"
  }
}

A missing, malformed, unknown, revoked or expired key gets 401:

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05"
  }
}

A key acts as its owner

Nextora runs each request as the key’s owner, with their role in the workspace. The key sees the records its owner can see and may do what their role allows — nothing more, whatever its scopes say.

A record the owner cannot see is 404 not_found, exactly like a record that does not exist.
An action their role does not allow is 403 forbidden.
Changes are made in the owner’s name: the activity log, owner_id defaults and note authors show them.

Scopes

Scopes limit what a key may do on top of its owner’s permissions. A request outside the key’s scopes is 403 insufficient_scope.

Scopes
Scope	Grants
`contacts:read`	List and retrieve contacts, notes on contacts, and contact custom-field definitions.
`contacts:write`	Create, update, delete and restore contacts; add, edit and delete notes on contacts.
`companies:read`	List and retrieve companies, notes on companies, and company custom-field definitions.
`companies:write`	Create, update, delete and restore companies; add, edit and delete notes on companies.
`deals:read`	List and retrieve deals, pipelines and their stages, notes on deals, and deal custom-field definitions. Also accepted by the forecast.
`deals:write`	Create, update, move, delete and restore deals; add, edit and delete notes on deals.
`tasks:read`	List and retrieve tasks and task custom-field definitions.
`tasks:write`	Create, update, complete, delete and restore tasks.
`leads:read`	List and retrieve leads, notes on leads, and lead custom-field definitions.
`leads:write`	Create, update, delete and restore leads; add, edit and delete notes on leads.
`users:read`	List the workspace’s users, to assign owners.
`analytics:read`	Read the forecast.
`webhooks:read`	List webhook subscriptions and their deliveries.
`webhooks:write`	Create, update and delete subscriptions; rotate secrets; send test events; retry deliveries.
`admin`	Every scope above. Only workspace admins can issue keys with it.

Pipelines and their stages are readable with deals:read.
Custom-field definitions are readable with the read scope of their record type.
Notes use the scopes of the record they belong to.
The forecast accepts analytics:read, or deals:read.
Keys can also hold scopes used only by the MCP server, such as automation:read or entities:write.

Rotating and revoking keys

Revoke a key in Settings → Developers → API keys when it is no longer needed or may have leaked; requests with it get 401 from then on. To rotate without downtime, create the new key, deploy it, check it is in use, then revoke the old one — both work in the meantime.

Keeping keys safe

Keep keys on servers, in environment variables or a secret manager. The API does not answer browsers (no CORS), so a key in front-end code is both useless and exposed.
One key per integration, with the fewest scopes that work. Revoking one then breaks nothing else.
Never commit keys. If one reaches a repository or a log, revoke it.
Workspace admins can issue admin keys. Use them only for administration tools.

AI clients connecting over MCP can sign in with OAuth 2.1 instead of a key — see MCP.