API Authentication - A2V2.ai Docs

Every Open API request authenticates with an API key and a matching secret, sent as request headers. Keys are created and managed in the dashboard, scoped to a single agent, and granted only the permissions you choose. This page covers creating a key, the scopes you can grant, and how to send credentials on each request. Open Settings → API Permissions in the dashboard to manage keys.

Prerequisites

Owner or Admin role — only Owners and Admins can create or change API keys.
The agent you want the key to act on, already created.

Create an API key

Open API Permissions

Go to Settings → API Permissions and select Add API Key.

Name the key and pick the agent

Give the key a recognizable name (for example, “Production sync”) and choose the agent it should act on. A key is scoped to one agent.

Grant permissions

Select which operations the key may perform. See Permission scopes below.

Save and copy the secret

Save the key. Copy the API key and secret immediately and store them securely — treat the secret like a password.

Store the API key and secret in a secure secret manager or environment variable. Never commit them to source control or expose them in client-side (browser) code — the Open API is a server-to-server interface. If a key is exposed, delete it in Settings → API Permissions and create a new one. Deleting a key immediately revokes access for any application using it.

Authenticate a request

Send both the key and the secret as headers on every request:

X-API-Key: your-api-key
X-API-Secret: your-api-secret
Content-Type: application/json

If either header is missing, the request is rejected with a message asking for the x-api-key and x-api-secret headers.

cURL
Node.js
Python

curl -X GET "https://api.a2v2.ai/v1/open/contacts/chatbots/<AGENT_ID>" \
  -H "X-API-Key: your-api-key" \
  -H "X-API-Secret: your-api-secret"

import axios from "axios";

const a2v2 = axios.create({
  baseURL: "https://api.a2v2.ai/v1/open",
  headers: {
    "X-API-Key": process.env.A2V2_API_KEY,
    "X-API-Secret": process.env.A2V2_API_SECRET,
    "Content-Type": "application/json",
  },
});

const { data } = await a2v2.get(`/contacts/chatbots/${agentId}`);

import os, requests

BASE = "https://api.a2v2.ai/v1/open"
headers = {
    "X-API-Key": os.environ["A2V2_API_KEY"],
    "X-API-Secret": os.environ["A2V2_API_SECRET"],
    "Content-Type": "application/json",
}

resp = requests.get(f"{BASE}/contacts/chatbots/{agent_id}", headers=headers)
resp.raise_for_status()
data = resp.json()

https://api.a2v2.ai is the production API base URL (see API Overview). Replace <AGENT_ID> with the ID of the agent the key is scoped to.

Permission scopes

Each key is granted permissions per resource, with separate create, read, update, and delete actions. A request that needs a permission the key doesn’t have is rejected.

Scope	Covers	Actions
Contact Access (`contacts`)	CRM contacts and contact files for the agent	create, read, update, delete
Document Extraction Access (`document-extraction`)	AI extraction of structured data from uploaded documents	create, read

Grant the narrowest set of actions a key actually needs. A read-only reporting integration, for example, only needs read on Contact Access.

Key settings

When you create or edit a key, you can also configure:

Setting	What it controls	Notes
Name	A label to identify the key	Required
Description	Free-text note on the key’s purpose	Optional
Permissions	The scopes and actions above	At least one required
Rate limits	Requests per minute / per hour	Defaults 60/min and 1,000/hour; configurable up to 1,000/min and 10,000/hour
Allowed IPs	Restrict use to specific IPv4 addresses or CIDR ranges	Optional; leave unset to allow any IP
Expiry	A date after which the key stops working	Optional

Scoping and isolation

A key only works for the agent it’s scoped to. Calling another agent’s endpoint with the wrong key is rejected.
Keys are scoped to your organization’s data only — there is no cross-tenant access.
Usage is tracked per key, so you can review activity in the dashboard.

Troubleshooting

401 / 'API key and secret are required'

Both X-API-Key and X-API-Secret headers must be present and spelled exactly. Confirm your client isn’t dropping custom headers on redirects.

403 / permission denied

The key lacks the required scope or action. Edit the key in Settings → API Permissions and grant the needed permission (for example, create on Contact Access to create contacts).

Requests work from one server but not another

The key may have an Allowed IPs restriction. Add the new server’s IP, or remove the restriction.

A key suddenly stopped working

Check whether it reached its expiry date or was deleted. Create a new key and update your integration’s stored credentials.

API Overview

Base URL, response format, and rate limits.

Endpoints

Every Open API endpoint, grouped by domain.

API keys in Settings

Manage keys from the dashboard.

CRM Contacts

Understand the contact data your API reads and writes.

​Prerequisites

​Create an API key

​Authenticate a request

​Permission scopes

​Key settings

​Scoping and isolation

​Troubleshooting

​Related

API Overview

Endpoints

API keys in Settings

CRM Contacts

Prerequisites

Create an API key

Authenticate a request

Permission scopes

Key settings

Scoping and isolation

Troubleshooting

Related