Skip to main content
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.
1

Log in to your Verbosec account

Visit verbosec.com and sign in with your credentials.
2

Go to Verbosec Cloud → API Keys

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

Click Generate New Key

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

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"

​
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

​
period_start
string
An ISO 8601 timestamp marking the start of the current billing period.
​
period_end
string
An ISO 8601 timestamp marking the end of the current billing period.
​
usage
object
An object containing your consumption totals for the billing period.

​
Authentication errors

When authentication fails, the API returns one of the following error responses.
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."
  }
}
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.