Agency Keys & Cross-Org Targeting

An agency is an org that manages a portfolio of client orgs linked in graph8 as parent → child. An agency can mint a single agency-scoped API key and use it to operate any of its client orgs through the entire Developer API — contacts, sequences, dialer, workflows, appointments, deals, everything — without minting one key per client.

Mint an Agency Key

POST /api-keys

Create an agency-scoped API key on the agency (parent) org by passing is_agency: true in the request body.

Request Body

Example

curl -X POST "https://be.graph8.com/api/v1/api-keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CIENCE agency ops",
    "is_agency": true
  }'

Response

{
  "data": {
    "id": "key_abc123",
    "name": "CIENCE agency ops",
    "is_agency": true,
    "token": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Errors

Cross-Org Targeting — X-Target-Org-Id

Once you have an agency key, send it with the X-Target-Org-Id header to act on a specific client org. The request then reads and writes that client org’s data.

Targeting Rules

Notes

• X-Target-Org-Id is honored on the Developer API (/api/v1/*) only. It is not used by in-app or customer-hub hybrid endpoints, which keep single-org semantics.
• X-Target-Org-Id is distinct from X-Org-Id. X-Org-Id remains a same-org safety guard; X-Target-Org-Id is the agency selector. Do not conflate them. For an agency key, X-Org-Id (if sent) still checks against the agency’s own org, independent of any X-Target-Org-Id.
• The target is always clamped against the agency’s live authorized client set — a caller-supplied value can only select within that set, never widen it.
• Billing: credit-consuming actions performed in a client org are charged to that client org, not the agency.
• Cross-org writes are supported, with one exception: destructive marketplace operations (for example, approving an SDR invoice that fires a Stripe charge) still require a personal admin key and are refused for agency machine keys.

Example

# List contacts in a specific client org
curl "https://be.graph8.com/api/v1/contacts" \
  -H "Authorization: Bearer $AGENCY_KEY" \
  -H "X-Target-Org-Id: org_client123"

# Create a contact in a client org
curl -X POST "https://be.graph8.com/api/v1/contacts" \
  -H "Authorization: Bearer $AGENCY_KEY" \
  -H "X-Target-Org-Id: org_client123" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": 5,
    "first_name": "Jane",
    "last_name": "Smith",
    "work_email": "[email protected]"
  }'

Get Agency Credential Info

GET /agency/me

Describe the agency credential associated with the current API key. Returns metadata about the agency org and the number of client orgs the key can target.

Example

curl "https://be.graph8.com/api/v1/agency/me" \
  -H "Authorization: Bearer $AGENCY_KEY"

Response

{
  "data": {
    "agency_org_id": "org_agency123",
    "agency_org_name": "CIENCE",
    "is_agency": true,
    "client_count": 52,
    "target_header": "X-Target-Org-Id"
  }
}

Errors

List Authorized Client Orgs

GET /agency/clients

List all client orgs this agency key is authorized to target. Each org_id in the response is a valid value for the X-Target-Org-Id header.

Example

curl "https://be.graph8.com/api/v1/agency/clients" \
  -H "Authorization: Bearer $AGENCY_KEY"

Response

{
  "data": [
    { "org_id": "org_client123" },
    { "org_id": "org_client456" }
  ]
}

Errors