Server Object & Credential Reference

Overview

The server object is a shared configuration shape used in several places across Sulus — on an assistant, a phone number, and inside an individual tool's configuration — to tell Sulus where to send webhook requests and how to authenticate them. This page is the field-by-field reference for the server object itself and the legacy-to-credential migration path. For credential CRUD operations (creating, listing, and deleting credentials via the API), see Credential API: Create, List, Delete & Auth Types; for a dashboard-first walkthrough of the same authentication concepts, see Credentials & Auth.

The server object supports the following fields:

The current recommended pattern is url plus credentialId — the inline secret and headers fields still work for backward compatibility, but new configurations should reference a credential instead of embedding secrets directly in the config.

Sulus uses a credential-based authentication system: you create a Custom Credential in the dashboard or via the API, choosing an authentication type (Bearer Token, OAuth 2.0, or HMAC), and reference the resulting credential by its id as credentialId wherever a server object appears. This keeps secret values out of your configuration files entirely — the config only ever contains a credential ID, not the underlying token or key.

If you have an existing server object using the legacy inline secret field, migrate it to a credentialId reference:

Before:

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

After:

1. Create a Bearer Token credential with the token value set to your existing secret, the header name set to match what your server already expects, and the Bearer-prefix option disabled if your server does not expect a Bearer prefix
2. Replace the secret field with credentialId pointing at that new credential's ID

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

The receiving server sees no behavior change — it still receives the same header with the same value on each request. Only the way Sulus stores and references that secret changes.

The same server object shape is used in three places:

• Assistant configuration — the default destination for that assistant's webhook events
• Phone number configuration — overrides the assistant-level server for events tied to a specific number
• Tool configuration — the destination for an individual tool's server-side execution (e.g., an API request tool)

A single credential can be reused across all three without duplicating secrets.

customerJoinTimeoutSeconds is a separate, assistant-level field (not part of the server object) that controls how long a user has to join a web call before it is automatically terminated.

If the user doesn't complete their network connection, grant microphone permissions, and finish WebRTC setup within this window, the call ends with an assistant-did-not-receive-customer-audio reason.

• Never expose a private API key or secret to the client (browser/mobile) side of your application — the server object and its credential are meant to protect your own backend endpoint, not to be embedded in client code
• Use descriptive credential names (e.g., "Production Webhook Auth") so it's clear what each credential is for when you're auditing usage later
• Rotate credentials on a regular schedule, and immediately after any suspected exposure — rotating in the dashboard doesn't require touching your assistant, phone number, or tool configuration
• Use environment-specific credentials — keep separate credentials for staging and production rather than reusing one across environments

In summary: the server object's url and credentialId fields are the current standard; the inline secret and headers fields remain for backward compatibility but should be migrated when convenient; and customerJoinTimeoutSeconds is a related but separate, web-call-only setting.