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

# API Authentication & Key Management

> How to authenticate requests using your Valuez AI API key

All requests to the **Valuez External Developer API** and **Integration APIs** require an API key. Your workspace administrator will provision and share this key with you before you begin development.

**Production Base URL**: `https://api.dashboard.valuez.ai`

***

## 1. How Authentication Works

Every API request must include the following HTTP header:

```http theme={null}
x-api-key: valuezai_api_YOUR_KEY_SECRET
```

* **Header Name**: `x-api-key`
* **Key Format**: `valuezai_api_<ID>_<secret>` (e.g. `valuezai_api_12_a8f3b2c9d4e5...`)
* **Scope & Credits**: Each key is bound to your workspace, specific permission scopes, and an optional credit usage limit.

***

## 2. Getting Your API Key

**API keys are provisioned and managed by your workspace administrator.** Contact your admin to receive:

1. Your **API key** (`valuezai_api_...`) — required for all API requests.
2. Confirmation of which **permission scopes** your key covers (see §5 below).

Once you have the key, store it as an environment variable in your backend. **Never hard-code it in source files.**

```bash theme={null}
# In your server's .env file
VALUEZ_API_KEY=valuezai_api_12_a8f3b2c9d4e5f678...
```

<Warning>
  Treat your API key like a password. If a key is accidentally exposed, notify your admin immediately so it can be rotated.
</Warning>

***

## 3. Configuring Postman

Your admin will also share the **Valuez External Developer API** Postman collection and **ValuezAI\_REST\_API** environment. After importing them, set these two environment variables:

| Variable | Description | Value |
| - | - | - |
| `BaseURL` | Production API host | `https://api.dashboard.valuez.ai` |
| `APIKey` | API key from your admin | `valuezai_api_12_a8f3b2c...` |

<Tip>
  The Postman collection is pre-configured with `x-api-key: {{APIKey}}` at the collection level. All requests inherit this automatically — no manual header setup needed for any endpoint.
</Tip>

***

## 4. Code Examples

Use the following examples to make your first authenticated API call (listing agents in your workspace):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.dashboard.valuez.ai/api/v1/external/agent/agent-list" \
    -H "x-api-key: $VALUEZ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "searchName": "",
      "pageNo": 1,
      "pageSize": 10,
      "sortColumn": "CreatedOn",
      "sortOrder": "DESC"
    }'
  ```

  ```javascript Node.js theme={null}
  const API_KEY = process.env.VALUEZ_API_KEY;
  const BASE_URL = "https://api.dashboard.valuez.ai";

  const response = await fetch(`${BASE_URL}/api/v1/external/agent/agent-list`, {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      searchName: "",
      pageNo: 1,
      pageSize: 10,
      sortColumn: "CreatedOn",
      sortOrder: "DESC"
    })
  });

  const data = await response.json();
  console.log("Agents:", data);
  ```

  ```python Python theme={null}
  import os
  import requests

  API_KEY = os.getenv("VALUEZ_API_KEY")
  BASE_URL = "https://api.dashboard.valuez.ai"

  response = requests.post(
      f"{BASE_URL}/api/v1/external/agent/agent-list",
      headers={
          "x-api-key": API_KEY,
          "Content-Type": "application/json"
      },
      json={
          "searchName": "",
          "pageNo": 1,
          "pageSize": 10,
          "sortColumn": "CreatedOn",
          "sortOrder": "DESC"
      }
  )
  print(response.json())
  ```
</CodeGroup>

***

## 5. Permission Scopes

When your admin provisions a key, it is assigned specific permission scopes. If a request touches an endpoint outside the key's allowed scopes, the server returns `403 Forbidden`.

| Scope | What It Allows |
| - | - |
| `agents` | Create, update, and read AI agent configurations, voice models, and knowledge bases. |
| `campaigns` | Create campaigns, import contacts, start/stop auto-dialer batches. |
| `team-management` | Invite workspace members, set roles, and revoke access. |
| `activity-logs` | Read conversation logs, call transcripts, and API usage history. |

***

## 6. Common Authentication Errors

| HTTP Status | Message | What to Do |
| - | - | - |
| `401 Unauthorized` | `"API Key missing"` | The `x-api-key` header is absent. Add the header to your request. |
| `400 Bad Request` | `"Invalid API key format"` | The key string is incomplete or malformed. Re-copy the full key from your admin. |
| `403 Forbidden` | `"Invalid API key"` | The key was deleted or deactivated. Contact your admin for a new key. |
| `403 Forbidden` | `"This API key has exceeded its individual credit limit."` | Contact your admin to top up workspace credits or raise the key's credit limit. |

<CardGroup cols={3}>
  <Card title="Look up IDs" icon="list" href="/dev-lookups">
    Query master values before creating agents or campaigns.
  </Card>

  <Card title="Speech & Agent APIs" icon="sparkles" href="/dev-integration-apis">
    Start sending questions and synthesizing speech.
  </Card>

  <Card title="Agents & Knowledge" icon="brain" href="/dev-agents-knowledge">
    Create and configure your first AI agent.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.