Credential API: Create, List, Delete & Auth Types

Overview

The credential resource is what authenticates outbound requests to your webhooks, tools, and phone number configs. This page is the API-level reference for creating, referencing, and deleting credentials. For a dashboard-first walkthrough of the same concepts, see Credentials & Auth; for an HMAC-specific deep dive on verifying signatures on your own server, see Webhook Signature Verification & Security.

Every credential is one of three authentication types:

Send a POST request to /credential. This example creates a webhook credential using OAuth 2.0:

curl -X POST "https://api.sulus.ai/credential" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "webhook",
    "name": "my-webhook-oauth2-credential",
    "authenticationPlan": {
      "type": "oauth2",
      "url": "https://your-url.com/oauth/token",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret"
    }
  }'

Once created, the core system requests a token from your endpoint using the client credentials flow, includes it in the Authorization header on webhook requests, and automatically refreshes it when it expires.

For a Bearer Token credential, the authenticationPlan object takes these fields:

For legacy inline-secret compatibility, set headerName to X-Sulus-Secret and bearerPrefixEnabled to false.

Once created, reference a credential by its returned id as credentialId anywhere a server object is used — on an assistant, a phone number, or in an individual tool's server config:

{
  "server": {
    "url": "https://your-server.sulus.ai/webhook",
    "credentialId": "cred_abc123"
  }
}

On an apiRequest tool specifically, set the same value in the tool's own credentialId field. The same credential can be reused across multiple assistants, phone numbers, and tools without duplicating secrets.

Beyond the API, the dashboard supports the same lifecycle: create a credential, edit its non-secret fields, delete it, and view usage tracking to see everywhere a given credential is currently referenced before you rotate or remove it.

Credential secrets (tokens, client secrets, HMAC keys) are encrypted at rest and cannot be viewed again once created — if you lose track of a secret's value, you'll need to create a new credential rather than retrieve the old one.