API Authentication & Key Management

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:

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:

Your API key (valuezai_api_...) — required for all API requests.
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.

# In your server's .env file
VALUEZ_API_KEY=valuezai_api_12_a8f3b2c9d4e5f678...

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

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...`

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.

4. Code Examples

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

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"
  }'

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);

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())

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.

Look up IDs

Query master values before creating agents or campaigns.

Speech & Agent APIs

Start sending questions and synthesizing speech.

Agents & Knowledge

Create and configure your first AI agent.

Getting started

Dashboards

Campaigns

Teams

Agents and knowledge

Reference

API Authentication & Key Management

1. How Authentication Works

2. Getting Your API Key

3. Configuring Postman

4. Code Examples

5. Permission Scopes

6. Common Authentication Errors

Look up IDs

Speech & Agent APIs

Agents & Knowledge

​1. How Authentication Works

​2. Getting Your API Key

​3. Configuring Postman

​4. Code Examples

​5. Permission Scopes

​6. Common Authentication Errors

Look up IDs

Speech & Agent APIs

Agents & Knowledge

1. How Authentication Works

2. Getting Your API Key

3. Configuring Postman

4. Code Examples

5. Permission Scopes

6. Common Authentication Errors