Authentication

Every request to the Nuvia API is authenticated with a Bearer token sent in the Authorization header. This page explains how to authenticate calls with an API key you already have. To generate, list, and revoke keys, see the API key guide.

Base URL

https://api.nuvia.ai

All REST API routes use the version prefix /v1. For example, listing agents is GET https://api.nuvia.ai/v1/agents.

The Nuvia API key doesn’t use an X-API-Key header or a token in the sk_... format. The key is sent as a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

Sending the key in X-API-Key results in 401, because the server doesn’t read that header.

Two ways to authenticate

The API accepts two types of identity in the same Authorization: Bearer header:

Company API key: this is what you use for programmatic integration. The key is linked to your company and to the scopes defined at creation; it can have an optional expiration (expiresAt). It’s the recommended method for servers, scripts, and integrations.
Human JWT: the session token issued by the application’s login flow (POST /v1/auth/login). It represents a human user, not an integration. You don’t need it to consume the API via API key. The login endpoints belong to the platform and don’t appear in the API reference, which covers the surface consumable by API key.

The server automatically identifies which of the two was sent from the token’s content itself. You don’t flag the type anywhere. For the rest of this documentation, we assume the use of a company API key.

Authenticating a request

Include the Authorization header in every call. The example below lists your company’s agents (requires the agents:read scope):

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

const res = await fetch("https://api.nuvia.ai/v1/agents", {
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
  },
});

const data = await res.json();

import os
import requests

res = requests.get(
    "https://api.nuvia.ai/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
)

data = res.json()

The API key is a full access token to the granted scope. Treat it as a secret: store it in an environment variable or secrets vault, never in source code or version control.

Multi-tenant and the `X-Company-Id` header

The tenant (company) of a company API key is resolved by the token itself. You don’t need to provide it. The X-Company-Id header is only required for internal-use global keys and is ignored for company API keys and for human JWTs. In short: when integrating with a company API key, you don’t send X-Company-Id.

Authentication errors

Authentication error responses follow the { statusCode, message, error } format.

401: not authenticated

Returned when the token is missing, invalid, expired, or revoked.

{
  "statusCode": 401,
  "message": "Invalid authentication",
  "error": "Unauthorized"
}

The message field details the cause when possible, for example "Invalid API key", "Expired API key", "Revoked API key", or "API key not found".

403: no permission

Returned when the token is valid, but the API key doesn’t have the scope required for the action, or the endpoint isn’t available for API keys.

{
  "statusCode": 403,
  "message": "API key doesn't have the scope required for this action",
  "error": "Forbidden"
}

If you get 403 on a call that should work, check whether the key was created with the scope required by the endpoint. Scopes are defined when the key is created. See the API key guide.

Getting started

Guides

Base URL

Two ways to authenticate

Authenticating a request

Multi-tenant and the `X-Company-Id` header

Authentication errors

401: not authenticated

403: no permission

Next steps

API key guide

Quickstart

​Base URL

​Two ways to authenticate

​Authenticating a request

​Multi-tenant and the X-Company-Id header

​Authentication errors

​401: not authenticated

​403: no permission

​Next steps

API key guide

Quickstart

Base URL

Two ways to authenticate

Authenticating a request

Multi-tenant and the `X-Company-Id` header

Authentication errors

401: not authenticated

403: no permission

Next steps