Authenticating with the Verbosec API

Every request you make to the Verbosec API must be authenticated. Authentication works by passing your API key as a Bearer token in the Authorization header. Without a valid key, the API rejects the request with a 401 Unauthorized response. Your API key is tied to your account and carries the permissions associated with your plan, so handle it with care.

Getting your API key

Follow these steps to generate a new API key from your Verbosec Cloud dashboard.

Visit verbosec.com and sign in with your credentials.

Go to Verbosec Cloud → API Keys

From your dashboard, navigate to Verbosec Cloud in the sidebar, then select API Keys from the sub-menu.

Click Generate New Key

Press the Generate New Key button, give the key a descriptive label (for example, production-backend), and confirm.

Copy and securely store your key

Your new API key is displayed only once. Copy it immediately and store it in a secure location such as a password manager or a secrets manager. You cannot retrieve it again after closing the dialog.

Passing the API key

Include your API key on every request inside the Authorization header using the Bearer scheme.

authenticated-request.sh

curl -X GET https://api.verbosec.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Never expose your API key in client-side code, browser JavaScript, or public repositories. Always load it from an environment variable or a secrets manager, and never commit it to version control.

Code examples

The examples below show how to make an authenticated GET /usage request in three common environments.

curl -X GET https://api.verbosec.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

import os
import requests

api_key = os.environ["VERBOSEC_API_KEY"]

response = requests.get(
    "https://api.verbosec.com/v1/usage",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
)

print(response.json())

const apiKey = process.env.VERBOSEC_API_KEY;

const response = await fetch("https://api.verbosec.com/v1/usage", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
});

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

Retrieve API usage

Once authenticated, you can retrieve your current usage statistics at any time by calling the GET /usage endpoint. This returns a summary of your API consumption for the current billing period across all Verbosec products. Endpoint

GET https://api.verbosec.com/v1/usage

Example request

get-usage.sh

curl -X GET https://api.verbosec.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

usage-response.json

{
  "period_start": "2025-01-01T00:00:00Z",
  "period_end": "2025-01-31T23:59:59Z",
  "usage": {
    "text_tokens": 125000,
    "images_generated": 48,
    "audio_seconds": 320,
    "file_chats": 15
  }
}

Response fields

string

An ISO 8601 timestamp marking the start of the current billing period.

string

An ISO 8601 timestamp marking the end of the current billing period.

object

An object containing your consumption totals for the billing period.

Show Usage fields

integer

The total number of text tokens consumed across all text generation requests.

integer

The total number of images generated.

integer

The total seconds of audio synthesised across all voice generation requests.

integer

The total number of file chat interactions performed.

Authentication errors

When authentication fails, the API returns one of the following error responses.

401 Unauthorized — Missing or invalid key

Returned when the Authorization header is absent or the API key is not recognised.

401-response.json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

403 Forbidden — Insufficient permissions

Returned when your API key is valid but your plan does not include access to the requested resource.

403-response.json

{
  "error": {
    "code": "forbidden",
    "message": "Your current plan does not include access to this resource."
  }
}

Create separate API keys for each environment — for example, one for development and one for production. If a key is ever compromised you can revoke it without affecting other environments.

Overview

Nexus AI API

Starhost API

Authenticating with the Verbosec API

Getting your API key

Passing the API key

Code examples

Retrieve API usage

Example request

Example response

Response fields

Authentication errors

​Getting your API key

​Passing the API key

​Code examples

​Retrieve API usage

​Example request

​Example response

​Response fields

​Authentication errors

Getting your API key

Passing the API key

Code examples

Retrieve API usage

Example request

Example response

Response fields

Authentication errors