Credentials & Auth

Overview

Sulus uses a credential-based authentication system for managing API keys and securing server endpoints. You create Custom Credentials in the dashboard and reference them by ID in your server configurations, rather than embedding secrets inline.

Sulus supports three types of authentication credentials:

Custom Credentials are managed through the Sulus dashboard under your organization settings. To create one:

1. Navigate to Custom Credentials in the dashboard
2. Choose your authentication type (Bearer Token, OAuth 2.0, or HMAC)
3. Enter a descriptive name (e.g., "Production API Auth")
4. Fill in the required fields for your chosen type
5. Save and note the generated credential ID (e.g., cred_abc123)

When creating a Bearer Token credential, configure:

• Token – Your API token or secret
• Header Name – The header to send the token in (default: Authorization)
• Include Bearer Prefix – Whether to prepend "Bearer " to the token value

Your server will receive requests like:

POST /webhook HTTP/1.1
Host: api.example.com
Authorization: Bearer your-api-token-here
Content-Type: application/json

For legacy compatibility, you can configure the header name as X-Sulus-Secret with the Bearer prefix disabled — this replicates the old inline secret field behavior.

When creating an OAuth 2.0 credential, configure:

• Token URL – Your OAuth token endpoint
• Client ID – OAuth client identifier
• Client Secret – OAuth client secret
• Scope – Optional scopes to request

Sulus handles the full token lifecycle automatically — requesting tokens, including them in webhook requests, and refreshing them when they expire.

Reference a credential by its ID anywhere a server object is used.

In an assistant:

{
  "server": {
    "url": "https://api.example.com/webhook",
    "credentialId": "cred_bearer_auth_123"
  }
}

In a phone number:

{
  "phoneNumber": "+1234567890",
  "server": {
    "url": "https://api.example.com/calls",
    "credentialId": "cred_oauth_456"
  }
}

In a tool:

{
  "type": "function",
  "function": { "name": "get_weather" },
  "server": {
    "url": "https://api.example.com/weather",
    "credentialId": "cred_hmac_789"
  }
}

The same credential ID can be reused across multiple assistants, phone numbers, and tools.

If you previously used the inline secret field, replace it with a credentialId reference:

Before:

{
  "server": {
    "url": "https://api.example.com/webhook",
    "secret": "your-secret-token"
  }
}

After:

{
  "server": {
    "url": "https://api.example.com/webhook",
    "credentialId": "cred_x_sulus_secret_123"
  }
}

• Use descriptive names like "Production API Key" or "Staging OAuth" to easily identify credentials
• Rotate credentials regularly — update them in the dashboard without changing your configurations
• Never share secrets — once created, credential secrets are encrypted and cannot be viewed in the dashboard
• Use environment-specific credentials — maintain separate credentials for staging and production environments

In summary, the credential-based system centralizes authentication management, making it easy to rotate secrets, audit usage, and reuse credentials across your entire Sulus configuration.