Authentication

Every request to the Novo Agents API is authenticated with a single bearer token. There is no OAuth, no signed-request shape, no per-resource keys: one key, sent on every call.

API keys

Create keys in the console under API keys. The secret is revealed once at creation; store it in your server's secret manager. The key is scoped to the workspace it was created in.

export NOVO_AGENTS_API_KEY=novo_ag_…

The SDK reads NOVO_AGENTS_API_KEY from the environment by default. Pass an explicit apiKey to override:

const novo = new NovoAgents({ apiKey: process.env.MY_OTHER_VAR });

Server-only

The SDK throws NovoConfigurationError with code browser_runtime if you try to instantiate it from a browser bundle. Your API key never belongs in client code.

If your frontend needs to drive a run, expose a thin route on your server that proxies stream.toResponse() back to the browser; see the Stream into a Next.js route guide.

Direct HTTP

If you cannot use the SDK, send the key as a Bearer token:

curl https://api.novoagents.ai/v1/agents \
  -H "Authorization: Bearer $NOVO_AGENTS_API_KEY"

Every authenticated response carries an X-Request-Id header you should log alongside your application's request ID. When you open a support ticket, the request ID is the fastest path to the matching run on our side.

Errors

| Status | Error type | SDK subclass | When | |---|---|---|---| | 401 | authentication_error | NovoAuthenticationError | Missing, revoked, or malformed key. | | 403 | permission_error | NovoPermissionError | Key valid but scoped out of the resource. |

Catch them with instanceof; see errors.

Rotation

Rotate a key at any time. The old secret stops accepting calls the moment the new one is shown. There is no overlap window; ship the new key, deploy, then revoke.