Skip to content

Credentials & Resources ​

Register the provider connections your agents use — the same connections you see on the Connections page — and find out what each one actually gives you: the phone numbers or email senders behind it, and which agent is using each one.

OperationEndpointScope
Register a connectionPOST /api/v1/credentialscredentials:write
List connectionsGET /api/v1/credentialscredentials:read
Get one connectionGET /api/v1/credentials/{id}credentials:read
List a connection's resourcesGET /api/v1/credentials/{id}/resourcescredentials:read

Registering a connection ​

bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/credentials" \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plivo — India numbers",
    "type": "plivo",
    "description": "Main support line",
    "config": { "auth_id": "…", "auth_token": "…" }
  }'
FieldValues
name1–200 characters
typeThe provider, e.g. plivo, aws_ses, meta_whatsapp, google_sheets
descriptionOptional
configThe provider's own fields — the same ones its form asks for on the Connections page

The response is 201 with the stored connection. A new connection starts as not_configured; open it on the Connections page and run its test to confirm it works.

You can register the same provider types the Connections page offers. AI model keys (Gemini, OpenAI, Sarvam and the like) are included and managed by Perfox, so registering one is refused with 403 credential_type_not_allowed — there is nothing to configure.

A Meta WhatsApp phone_number is stored in international (E.164) format; send it with its + and country code (for example +919876543210), or the request is refused with 400 bad_request.

Secrets are never returned ​

No read ever returns a secret. Every connection comes back as:

FieldMeaning
id, name, type, descriptionAs registered
statusconnected, error, not_configured or pending_verification
config_fieldsThe names of the config keys that are set — never their values
last_testedWhen it was last tested, or null
created_at / updated_atTimestamps

config_fields lets you confirm a registration worked (for example that auth_token was stored) without anyone being able to read the value back. GET /api/v1/credentials returns up to 200 connections, newest first, with has_more: true when there are more.

A connection is not its resources ​

GET /api/v1/credentials/{id} answers "is this provider connected". The resources call answers the question you usually have next: which numbers does that account give me, what can each one do, and who is using it.

bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/credentials/{id}/resources" \
  -H "Authorization: Bearer sk_…"
json
{
  "data": [
    {
      "identifier": "+918000000001",
      "label": "+918000000001 (Plivo)",
      "channel": "phone",
      "capabilities": ["voice"],
      "provider": "plivo",
      "status": "active",
      "assigned_agent": { "id": "…", "name": "Sales Assistant" }
    },
    {
      "identifier": "+918000000002",
      "label": "+918000000002 (Plivo)",
      "channel": "whatsapp",
      "capabilities": ["whatsapp"],
      "provider": "plivo",
      "status": "active"
    }
  ]
}

An unknown id returns 404 not_found.

The channel is the purpose ​

channelWhat the identifier is for
phoneVoice calls
smsText messages
whatsappWhatsApp
emailEmail sending

Agent assignment ​

When an agent claims an identifier, the entry carries assigned_agent with that agent's id and name.

When nothing claims it, the field is absent rather than null — an unassigned spare number is a normal state, not missing data. One identifier belongs to at most one agent (the rule the agent builder enforces), so this is a single value and not a list.

The assignment is read from the agents themselves at request time rather than from a stored copy, so a number you rebind in the builder is correct here immediately.