Authentication

The four kinds of credential

Your tenant API key

Each Silux Chat account has one API key, shown in Dashboard → API Settings. It identifies your account on the platform API: creating tickets (/api/chatbot-api/create-ticket), managing your sandbox and webhooks (/api/sandbox/*) and the other endpoints in the platform API reference.

X-API-Key: <your tenant API key>

• Pressing Regenerate in API Settings issues a new key and the old one stops working immediately.
• Your sandbox has its own separate key (beginning sbx_) that can never touch live data.
• A missing or unknown key returns 401 with {"detail":"Invalid API key"}.

curl -s "https://www.siluxchat.com/api/sandbox/webhooks" \
  -H "X-API-Key: invalid"

{"detail": "Invalid API key"}

Account Connect key

When you build the five Account Connect endpoints, you choose the key. Generate a long random value, store it in your server’s secret store, and enter the same value in Dashboard → Integrations → Account Connect. Silux Chat sends it on every request.

openssl rand -base64 36 | tr '+/' '-_' | tr -d '='

Checking it on your side

Compare the incoming key in constant time so an attacker cannot learn it one character at a time from response timings, and reject the request before doing any work.

import hmac, os
from fastapi import Header, HTTPException

API_KEY = os.environ["ACCOUNT_CONNECT_API_KEY"]

def require_key(x_api_key: str = Header(None)):
    if not x_api_key or not hmac.compare_digest(x_api_key, API_KEY):
        raise HTTPException(401, {"success": False, "message": "Missing or wrong X-API-Key"})

Connector credentials

A ready-made connector uses whatever your vendor issues. Each connector page lists exactly which fields it asks for and where to find them. Always create the key with read-only permissions.

• Credentials are encrypted before they are stored and are never shown again after saving — the dashboard shows only that a value is set.
• Every connection is tested with a real call before it is marked working, using a made-up customer so no real record is read.
• Disconnecting deletes the stored credentials outright, not merely hides them.

OAuth sign-in

For vendors that support it, the dashboard shows Sign in with <vendor> instead of key fields. You never handle a token.

1. 1
   You press Sign in with <vendor>. Silux Chat creates a pending connection with a random state value and sends you to the vendor’s consent screen, requesting only the read scopes listed on that connector’s page.
2. 2
   You approve access at the vendor.
3. 3
   The vendor redirects to https://www.siluxchat.com/api/connectors/oauth/callback with a one-time code and the same state. A callback whose state does not match a pending connection is rejected.
4. 4
   Silux Chat exchanges the code for tokens, encrypts them, runs the connection test and returns you to Dashboard → Integrations with the result.
5. 5
   Access tokens are refreshed automatically shortly (about 60 seconds) before they expire, so the bot never meets an expired token mid-conversation.

Client credentials

Connectors marked client_credentials (for example commercetools) take a client ID and secret. Silux Chat requests a short-lived access token from the vendor when needed and renews it before it expires; the secret itself is only ever sent to the vendor’s token endpoint.

Per-connection access keys

When you press Use to verify customers on a connector, Silux Chat exposes that connection through the standard Account Connect endpoints at:

https://www.siluxchat.com/api/connect/{connection_id}/verify-identity
https://www.siluxchat.com/api/connect/{connection_id}/verify-otp
https://www.siluxchat.com/api/connect/{connection_id}/account-summary
https://www.siluxchat.com/api/connect/{connection_id}/orders | invoices | bookings | subscriptions | tickets

• These are called by your bot, not by you. They are protected by a per-connection access key beginning scc_, generated automatically.
• Only a SHA-256 hash of the key is kept for checking requests. The key is never displayed.
• Each press of Use to verify customers mints a new key and retires the previous one.
• Disconnecting the connector deletes the key and switches the bot’s account tools off.

curl -s -X POST "https://www.siluxchat.com/api/connect/1/verify-identity" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Jane Demo","email":"jane.demo@example.com"}'

{
  "detail": {
    "success": false,
    "message": "Missing or wrong X-API-Key"
  }
}

Key rotation

import hmac, os
KEYS = [k for k in (os.environ.get("AC_KEY"), os.environ.get("AC_KEY_PREVIOUS")) if k]

def key_ok(given: str) -> bool:
    return bool(given) and any(hmac.compare_digest(given, k) for k in KEYS)

Authentication errors

FastAPI wraps error bodies in detail. Account Connect and connector endpoints put a structured object inside it; the platform API uses a string.

curl -s -X POST "https://www.siluxchat.com/api/account-connect-demo/v1/verify-identity" \
  -H "X-API-Key: wrong-key" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Test Customer","postcode":"TE5 7ST"}'

{"detail": {"success": false, "message": "Missing or wrong X-API-Key"}}

The correct key for the demo is demo-account-connect-key. See Troubleshooting for every other error.

Get help

Unsure which scopes to grant, or need a vendor’s OAuth sign-in prioritised? Email support@siluxcall.co.uk. Never include a live key in your email — we will never ask for one.