Skip to content
alzafchat / Developers

Documentation / Integrations

Server identity exchange

Use a server-side service key to issue scoped user tokens.

Integration guide
On this pageSet up a serviceExchange contractHost-side example (Node.js 22)Key management API

This integration is implemented by the standalone Alzaf Chat server, not by the embedded Composer package. Your backend authenticates its existing customer or seller and exchanges that verified identity for a 15-minute user-scoped token. Your frontend consumes that token with any supported chat adapter. Administrator accounts use the Alzaf Chat website login; keys cannot issue administrator roles.

Set up a service#

  1. A platform administrator creates your service and its providers under Workspace → Services and Merchants & teams. Provider IDs are stable identifiers, not names.
  2. A platform or service administrator opens Integrations, selects the service, enters a key name and optionally enables seller identities. Customer identities are always enabled by the website form. Generate key and store the shown secret in the host server's private environment, for example ALZAF_CHAT_SERVICE_KEY. This example variable belongs to your host; Alzaf Chat does not load it itself.
  3. Keys expire after 90 days. There may be at most 10 active keys per service. The secret is shown once, stored only as a SHA-256 hash, and never returned by the list API. Rotate before expiry: create another key, replace your server's secret, then revoke the old key. Revocation invalidates all tokens from that key.
  4. Configure the chat API and Reverb origin allowlists for your frontend. See configuration. CORS never grants identity or service access.

The service key can impersonate its allowed customer/seller roles across its own service. Treat it as a privileged server credential. Never embed it in Next.js public environment variables, browser JavaScript, logs, URLs or a script tag.

Exchange contract#

POST /api/integrations/exchange, HTTPS, headers Accept: application/json, Content-Type: application/json, Authorization: Bearer <service key>. The central API applies an IP throttle of 60 requests/minute. A shared host serving many users must account for that limit; no higher-load SLA is claimed.

json
{"external_id":"customer-123","name":"Example Customer","role":"customer"}

external_id is required, 1–120 characters, starts with an ASCII letter/digit, then letters, digits, _ . : @ -. It is scoped to the key's service. Keep it stable and prefer an opaque ID rather than personal data. name is required, maximum 120 characters. role must be in the key's customer/seller allowlist. A seller also supplies provider_id for an active provider in that same service; customers must omit it or send null. Browser-supplied service IDs cannot override key scope.

json
{"data":{"token":"USER_SCOPED_TOKEN","expires_at":"2026-10-07T15:15:00+00:00","user":{"id":"123","name":"Example Customer","email":"[email protected]","role":"customer","service_id":"example-service","provider_id":null,"is_active":true,"is_external":true,"active_service_id":"example-service","can_manage_services":false,"can_manage_accounts":false}}}

The ID is the central chat identity, not your host ID. Repeating an external ID reuses that identity and updates its display name. Role/provider mapping is immutable: use a separate external ID for a different role/provider. A host ID in another service produces a separate account. Existing website accounts are never linked by email. Mapped accounts cannot use email/password login or change their identity/password through account management; admins may disable them.

401 means missing/invalid/expired/revoked key or inactive service/account; 422 means validation, disallowed role or invalid provider; 409 means mapping conflict; 402 means new-account subscription capacity is unavailable; 429 means throttle. No refresh token exists. Your host session endpoint requests a new exchange when needed; role/provider changes require a separate mapping and revoking/disabling the old access. Tokens already issued remain valid for at most 15 minutes unless the key/account/service is revoked or disabled. Host logout alone does not revoke issued central tokens; use the user token's /api/auth/logout endpoint as well.

Host-side example (Node.js 22)#

Run this code only after your application's normal session middleware. The session object below must come from that middleware, never from request JSON. Validate the user's current seller membership on every token request. Protect your endpoint against cross-site requests using your host's session/CSRF policy.

js
export async function chatSession(session) {
  if (!session?.user?.id) throw new Error('Sign in first');
  const role = session.user.isSeller ? 'seller' : 'customer';
  const payload = {
    external_id: `${role}-${session.user.id}`,
    name: session.user.displayName,
    role,
    ...(role === 'seller' ? {provider_id: session.user.authorizedChatProviderId} : {}),
  };
  const response = await fetch('https://api.alzafchat.com/api/integrations/exchange', {
    method: 'POST',
    headers: {'Accept': 'application/json', 'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.ALZAF_CHAT_SERVICE_KEY}`},
    body: JSON.stringify(payload),
    cache: 'no-store',
  });
  if (!response.ok) throw new Error(`Chat session unavailable (${response.status})`);
  return (await response.json()).data; // Return user token to this user only.
}

This function illustrates the verified exchange contract; integrating a real host session still requires host code and permission tests. A runnable local Node host example is not supplied in this release. Do not describe every backend as a verified integration merely because it can call HTTP.

Pass the resulting token via a callback to the React/Next.js, Vue, SDK or HTML widget client. The callback should fetch your own authenticated host endpoint, never call the exchange with a service key from the browser. Keep tokens in memory and refresh before expiry; retry an expired request with a newly exchanged user token.

Key management API#

Bearer admin user token, prefix /api/admin/integration-keys:

MethodRequestBehavior
GET?service_id=...Latest 100 keys; metadata only, including revoked/expired records
POST{service_id,name,allowed_roles:["customer"],client_request_id:UUID}Creates key; returns metadata plus one-time secret
POST /{id}/revoke{service_id}Idempotent revocation and token deletion

Platform admins must select a service (query/body or active service). Service admins can manage only their stored service; customers/sellers receive 403. Cross-service key access is 404; attempts to select another service are 403. Repeating a creation UUID returns 409 without replaying the secret. If a network failure loses a created secret, refresh the list, revoke that key, and create a new one. Creation/revocation/identity creation write scoped audit events without secrets or message bodies. The list does not paginate beyond its latest 100 rows.