> ## Documentation Index
> Fetch the complete documentation index at: https://help.verbosec.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating with the Verbosec API

> Authenticate Verbosec API requests using Bearer tokens. Learn how to generate your API key and pass it in the Authorization header.

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.

<Steps>
  <Step title="Log in to your Verbosec account">
    Visit [verbosec.com](https://verbosec.com) and sign in with your credentials.
  </Step>

  <Step title="Go to Verbosec Cloud → API Keys">
    From your dashboard, navigate to **Verbosec Cloud** in the sidebar, then select **API Keys** from the sub-menu.
  </Step>

  <Step title="Click Generate New Key">
    Press the **Generate New Key** button, give the key a descriptive label (for example, `production-backend`), and confirm.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Passing the API key

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

```bash authenticated-request.sh theme={null}
curl -X GET https://api.verbosec.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  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.
</Warning>

## Code examples

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.verbosec.com/v1/usage \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript (fetch) theme={null}
  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);
  ```
</CodeGroup>

## 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

```bash get-usage.sh theme={null}
curl -X GET https://api.verbosec.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```json usage-response.json theme={null}
{
  "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

<ResponseField name="period_start" type="string">
  An ISO 8601 timestamp marking the start of the current billing period.
</ResponseField>

<ResponseField name="period_end" type="string">
  An ISO 8601 timestamp marking the end of the current billing period.
</ResponseField>

<ResponseField name="usage" type="object">
  An object containing your consumption totals for the billing period.

  <Expandable title="Usage fields">
    <ResponseField name="usage.text_tokens" type="integer">
      The total number of text tokens consumed across all text generation requests.
    </ResponseField>

    <ResponseField name="usage.images_generated" type="integer">
      The total number of images generated.
    </ResponseField>

    <ResponseField name="usage.audio_seconds" type="integer">
      The total seconds of audio synthesised across all voice generation requests.
    </ResponseField>

    <ResponseField name="usage.file_chats" type="integer">
      The total number of file chat interactions performed.
    </ResponseField>
  </Expandable>
</ResponseField>

## Authentication errors

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

<Accordion title="401 Unauthorized — Missing or invalid key">
  Returned when the `Authorization` header is absent or the API key is not recognised.

  ```json 401-response.json theme={null}
  {
    "error": {
      "code": "unauthorized",
      "message": "Invalid or missing API key."
    }
  }
  ```
</Accordion>

<Accordion title="403 Forbidden — Insufficient permissions">
  Returned when your API key is valid but your plan does not include access to the requested resource.

  ```json 403-response.json theme={null}
  {
    "error": {
      "code": "forbidden",
      "message": "Your current plan does not include access to this resource."
    }
  }
  ```
</Accordion>

<Tip>
  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.
</Tip>