Authentication
All Partner API requests require a Bearer token in the Authorization header. Partner API keys are provisioned by the OpenCX team — they are separate from org-level API keys.
Authorization: Bearer YOUR_PARTNER_API_KEY
https://api.open.cx
Create Org
Create a new organization for one of your customers.
Request body
| Field | Type | Required | Description |
|---|
name | string | Yes | Display name for the org. |
external_id | string | No | Your internal ID for this customer. Must be unique per partner — duplicates return 409. |
website | string | No | Customer’s website URL. |
language | string | No | Default language code (e.g. "en", "es", "de"). Defaults to "en". |
ai_instructions | string | No | The AI profile — system prompt that defines the agent’s personality, knowledge scope, and behavior. Overrides your partner-level default if set. |
integrations | object | No | Auto-connect integrations during creation. See below. |
Integrations
Pass integration credentials in the integrations object to auto-connect them during org creation. Credentials are validated against the live third-party API — invalid credentials cause the request to fail with a 400.
{
"integrations": {
"fareharbor": {
"app_key": "...",
"user_key": "...",
"default_company_shortname": "..."
}
}
}
More integrations will be added to the partner provisioning API over time. For integrations not yet supported here, use the org-level dashboard or API after creation.
Response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Tours",
"widget_token": "f8e7d6c5b4a39281...",
"external_id": "customer-12345"
}
| Field | Type | Description |
|---|
id | string | The org UUID. Use this to manage the org via other OpenCX APIs. |
name | string | The org name as provided. |
widget_token | string | Widget embed token. Pass this to the chat widget. |
external_id | string | null | Your external ID, echoed back. |
Error responses
| Status | Condition | Body |
|---|
400 | Invalid request body, or integration credentials failed validation. | { "statusCode": 400, "message": "..." } |
401 | Missing, invalid, or revoked API key. | { "statusCode": 401, "message": "..." } |
409 | An org with this external_id already exists for your partner. | { "statusCode": 409, "message": "Org with external_id \"...\" already exists" } |
Examples
curl -X POST https://api.open.cx/partner/v1/orgs \
-H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Tours",
"external_id": "customer-12345",
"language": "en",
"ai_instructions": "You are a support agent for Acme Tours. Help customers with bookings and questions."
}'
List Orgs
List all organizations created by your partner account.
Query parameters
| Parameter | Type | Default | Description |
|---|
limit | number | 50 | Number of orgs to return (1–100). |
offset | number | 0 | Number of orgs to skip (for pagination). |
Response
{
"data": [
{
"id": "a1b2c3d4-...",
"name": "Acme Tours",
"widget_token": "f8e7d6c5b4a3...",
"external_id": "customer-12345",
"created_at": "2026-03-15T10:30:00.000Z"
}
],
"total": 142
}
Examples
curl "https://api.open.cx/partner/v1/orgs?limit=10&offset=0" \
-H "Authorization: Bearer YOUR_PARTNER_API_KEY"
Create Org API Key
Create an API key for a specific org. The returned key authenticates requests to the OpenCX Public API (crawling, training, contacts, etc).
POST /partner/v1/orgs/:orgId/api-keys
Request body
| Field | Type | Required | Description |
|---|
name | string | No | A label for the key (e.g. "Production"). Defaults to "Default". |
Response
{
"api_key_id": "key-uuid-here",
"api_key": "eyJhbGciOi..."
}
| Field | Type | Description |
|---|
api_key_id | string | The key’s UUID. |
api_key | string | The JWT API key. Use this as Bearer token for org-level API calls. |
The full API key is only returned once — store it securely. If lost, create a new one.
Examples
curl -X POST https://api.open.cx/partner/v1/orgs/ORG_ID/api-keys \
-H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Production" }'
Error responses
| Status | Condition |
|---|
401 | Invalid or revoked partner API key. |
403 | Org does not belong to this partner. |
Invite User to Org
Send a dashboard invitation to a user. The invited user receives an email with a link to create their account and join the org.
POST /partner/v1/orgs/:orgId/invitations
Request body
| Field | Type | Required | Description |
|---|
email | string | Yes | Email address to invite. |
role_ids | string[] | No | Array of role UUIDs to assign. Defaults to admin if omitted. |
Response
{
"data": { "success": true }
}
Error responses
| Status | Condition |
|---|
400 | Email already has an active invitation, or is already a member of the org. |
401 | Invalid or revoked partner API key. |
403 | Org does not belong to this partner. |
Examples
curl -X POST https://api.open.cx/partner/v1/orgs/ORG_ID/invitations \
-H "Authorization: Bearer YOUR_PARTNER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]" }'
Idempotency
Use external_id to prevent duplicate orgs. If you call POST /partner/v1/orgs twice with the same external_id, the second call returns 409 Conflict. This makes it safe to retry org creation without risk of duplicates. Use GET /partner/v1/orgs to find the existing org.
The external_id uniqueness constraint is scoped to your partner account. Different partners can use the same external_id values.
