Nova Help

Authenticate with OAuth 2.1 or an API key

Get a token as a connected app (OAuth 2.1 with PKCE), as an AI teammate (client credentials) or as an integration (API key), and send it on every call.

Updated in release 0.0.1

Nova is its own OAuth 2.1 authorization server. Discovery documents live at the origin root, so a standards-based client needs only the base URL:

GET https://app.novabmp.com/.well-known/oauth-authorization-server
GET https://app.novabmp.com/.well-known/oauth-protected-resource

Connected apps: authorization code with PKCE

Use this when a person connects your app to their own Nova account.

  1. Register your client once (dynamic registration is open to public clients):
POST /oauth/register
Content-Type: application/json

{"client_name": "My assistant", "redirect_uris": ["https://example.com/callback"],
 "grant_types": ["authorization_code", "refresh_token"], "token_endpoint_auth_method": "none"}

The response carries client_id. Keep the registration_access_token if you want to read or delete the registration later.

  1. Send the person to /oauth/authorize with response_type=code, your client_id, a registered redirect_uri, the scope you need (space separated, see below), a random state, and a PKCE code_challenge (S256). Nova shows them what you ask for; they choose the organization and whether you act as them or as one of their agent teammates.

  2. Exchange the code:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...

You receive access_token (a short-lived JWT), refresh_token and the granted scope. Refresh with grant_type=refresh_token; each refresh token works once and replaying one revokes the whole connection.

AI teammates and integrations: client credentials

A person in the organization adds the AI teammate under Administration › Team & Access › AI Teammates (or the API key under Administration › Integrations & API › API & Connected Apps) and gives you a client_id and secret.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...&scope=accounts:read quotes:write

An organization API key can also be sent directly as a bearer token (Authorization: Bearer nova_live_...) without exchanging it first.

Sending the token

GET /v1/crm/accounts/?q=smith
Authorization: Bearer <access_token>

Machine credentials are bound to one organization; you do not send X-Organization-ID. A browser session token must send it.

Scopes

A scope value is a space-separated list of bundles (short names such as accounts:read, invoices:write, files:write, organization:read, help:read), permission keys (such as billing.invoices.void), or both. Bundles expand to the permission keys they stand for; the full list is in Scopes reference. A grant narrows a token to what it needs and never widens what the person or AI teammate could do themselves. Anything an organization can do can be granted, including deletes, voids and settings; a grant is refused only when it reaches past what the person approving it holds.

Revoking

  • A person disconnects an app from Profile › Connected apps.
  • An admin disconnects any app or revokes an API key under Administration › Integrations & API › API & Connected Apps, and pauses or retires an AI teammate under Administration › Team & Access › AI Teammates.
  • A client can revoke its own token at POST /oauth/revoke.

Tokens stop working immediately; there is no grace period.

Was this helpful?