Skip to main content

​
Authentication

The Nedzo API uses Bearer token authentication. All API requests must include your API key in the Authorization header.

​
API Keys

API keys are created in the Nedzo dashboard and can be scoped to:
  • Account-level: Access all workspaces in your account
  • Workspace-level: Access only a specific workspace
The scope you choose affects whether you need to include workspaceId in your requests. See Workspace ID and Request Scope below.

​
Workspace ID and Request Scope

Most resources in Nedzo (contacts, agents, templates, calls) belong to a specific workspace. How you identify the target workspace depends on the type of API key you’re using.

​
Workspace-scoped keys

A workspace-scoped key is locked to a single workspace. You do not need to send workspaceId — the API infers it from the key. 
# sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (workspace-scoped key)
curl -X POST "https://api.nedzo.ai/v1/contacts" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "phone": "+14155551234"
  }'
Scope is determined when the key is created in the dashboard — it’s not encoded in the key prefix. Both account and workspace keys use the same sk_live_* / sk_test_* format.

​
Account-scoped keys

An account-scoped key can act on any workspace in your account. You must send workspaceId in the request body (or query string for list endpoints) so the API knows which workspace to target. Omitting it returns: 
{
  "type": "https://api.nedzo.ai/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "workspaceId is required for account-scoped API keys"
}
Same example with an account-scoped key: 
# sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (account-scoped key)
curl -X POST "https://api.nedzo.ai/v1/contacts" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
    "firstName": "John",
    "phone": "+14155551234"
  }'

​
Endpoints where the workspace is implicit

Some endpoints don’t need workspaceId because the workspace is already determined by the resource you’re addressing or by the API key itself:
  • Path-scoped resources like GET /v1/contacts/{id}, PATCH /v1/agents/{id} — the resource’s workspace is looked up from its ID.
  • POST /v1/call — uses agentId to infer the workspace.
  • Workspace-scoped endpoints like /v1/workspaces/{workspaceId}/billing/... — the workspace is in the URL path.
  • List endpoints like GET /v1/agents, GET /v1/templates, GET /v1/contacts — workspace-scoped keys list within their workspace; account-scoped keys list across all workspaces (grouped or filterable via workspaceId).
  • /v1/workspaces CRUD — GET /v1/workspaces returns workspaces the key can access; POST /v1/workspaces creates inside the key’s account; GET|PATCH|DELETE /v1/workspaces/{id} operate on the path-scoped workspace.

​
Finding your workspace ID

You can get a workspace ID from the dashboard (Settings → Workspaces) or via the API: 
curl https://api.nedzo.ai/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"
The response includes id for each workspace your key can access.

​
Making Authenticated Requests

Include your API key in the Authorization header: 
curl https://api.nedzo.ai/v1/workspaces \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

​
API Key Format

Nedzo API keys follow this format:
EnvironmentFormatExample
Productionsk_live_*sk_live_abc123...
Testsk_test_*sk_test_xyz789...

​
Error Responses

If authentication fails, you’ll receive a 401 Unauthorized response: 
{
  "type": "https://api.nedzo.ai/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

​
Security Best Practices

API keys should only be used in server-side code. Never include them in JavaScript that runs in browsers or mobile apps.
Store API keys in environment variables, not in your codebase.
export NEDZO_API_KEY=sk_live_xxxxxxxx
Periodically rotate your API keys, especially if you suspect they may have been compromised.
When possible, use workspace-scoped keys to limit the blast radius if a key is compromised.

​
Rate Limits

API requests are rate-limited to ensure fair usage:
PlanRequests per minute
Free60
Pro300
EnterpriseCustom
When rate limited, you’ll receive a 429 Too Many Requests response with a Retry-After header.