Authentication

Assistant authentication runs at the start of a conversation. Rapida calls your authentication service before the assistant, tools, STT, TTS, or AgentKit backend starts. Use it to verify the user, tenant, subscription, account state, or channel context for the live session.

This is not Rapida API authentication. Rapida API authentication controls who can manage assistants and start sessions. Assistant authentication controls whether one conversation should continue, and what extra context should be added to that conversation.

Configure in Rapida Console

Open the assistant

In Rapida Console, open the assistant you want to protect.

Open Configure Assistant

Go to Configure Assistant and open the Authentication configuration.

Enable authentication

Turn on authentication for the assistant. If authentication is disabled or no authentication configuration exists, Rapida skips this step and the conversation continues normally.

Select HTTP provider

Choose HTTP as the authentication provider. HTTP is the supported provider for assistant authentication.

Enter endpoint details

Add the authentication endpoint URL, method, timeout, static headers, and request body mapping.

Choose failure behavior

Use Block when authentication is required. Use Allow only when the endpoint is used for optional enrichment.

Save and test

Save the configuration, then test from the target channel, such as Debugger, Phone Call, Web Widget, Web App, or WhatsApp.

What to configure

Console field	Runtime key	Required	Description
Provider	`provider=http`	Yes	Calls an external HTTP service. Other providers are not supported for assistant authentication.
Endpoint URL	`http_url`	Yes	Full URL of your authentication endpoint.
Method	`http_method`	No	Defaults to `POST`. Supported write methods are `POST`, `PUT`, and `PATCH`; other values are sent as `GET`.
Headers	`http_headers`	No	Static headers sent to the authentication endpoint. Use this for fixed integration headers.
Body mapping	`http_body`	Yes	Maps Rapida conversation variables into the JSON body sent to your endpoint.
Timeout	`timeout_ms`	No	Defaults to `5000` milliseconds.
Failure behavior	`fail_behavior`	No	Defaults to `block`. Controls non-`2xx` authentication responses.
Apply when / condition	`authentication.condition`	No	Limits authentication to specific source, mode, or direction values.

Configure a valid body mapping. If the body mapping is missing or invalid, Rapida cannot build authentication arguments and the session continues unauthenticated.

Request body mapping

The body mapping is not a literal JSON body. It maps source variables to request body field names. Example body mapping:

{
  "client.phone": "phone",
  "metadata.tenant": "tenant",
  "conversation.id": "conversationId",
  "argument.customerId": "customerId",
  "custom.source": "rapida"
}

If the session has phone +14155550123, tenant acme, conversation ID 2230142097179373568, and argument customerId=cust_123, Rapida sends this body:

{
  "phone": "+14155550123",
  "tenant": "acme",
  "conversationId": "2230142097179373568",
  "customerId": "cust_123",
  "source": "rapida"
}

Use these namespaces in the mapping:

Namespace	Example	Use for
`assistant.*`	`"assistant.id": "assistantId"`	Active assistant fields.
`conversation.*`	`"conversation.id": "conversationId"`	Current conversation fields.
`session.*`	`"session.source": "source"`	Session source and mode.
`argument.*`	`"argument.customerId": "customerId"`	Runtime arguments passed when the session starts.
`metadata.*`	`"metadata.tenant": "tenant"`	Conversation metadata.
`option.*`	`"option.agentkit.url": "agentkitUrl"`	Runtime options.
`client.*`	`"client.phone": "phone"`	Client metadata projected from `metadata.client.*`.
`custom.*`	`"custom.source": "rapida"`	Literal values. The suffix becomes the request field name and the value becomes the request field value.

Unknown or unavailable variables are skipped. Your authentication service should reject requests that are missing required fields.

Endpoint response

Return any 2xx status code to authenticate the session. The response body can be empty, or it can return overrides that Rapida merges before the assistant runtime starts.

{
  "args": {
    "customerName": "Jane",
    "plan": "enterprise"
  },
  "metadata": {
    "customerId": "cust_123",
    "tenant": "acme"
  },
  "options": {
    "experience.greeting": "Hi Jane, I found your account.",
    "agentkit.metadata": {
      "tenant": "acme",
      "customerId": "cust_123"
    }
  }
}

Response field	What it does
`args` or `arguments`	Adds or overrides runtime arguments. Use these for prompt variables such as customer name, plan, case ID, or order ID.
`metadata`	Adds or overrides conversation metadata. Use these for tenant, customer ID, routing label, audit ID, or authenticated user ID.
`options`	Adds or overrides runtime options. Use these for dynamic greeting, AgentKit metadata, model settings, or other supported runtime options.

Returned values override existing values with the same key. Nested maps are merged, so returning agentkit.metadata.tenant can add tenant routing context without replacing unrelated AgentKit metadata.

Failure behavior

Situation	Result
No authentication configuration	Authentication is skipped and the conversation continues.
Authentication disabled	Authentication is skipped and the conversation continues.
Condition does not match	Authentication is skipped and the conversation continues unauthenticated.
Missing or invalid body mapping	Authentication arguments cannot be built; the conversation continues unauthenticated.
Missing endpoint URL	Authentication execution fails and the session stops.
Endpoint timeout or network error	Authentication execution fails and the session stops.
Endpoint returns `2xx`	Session is authenticated. Returned `args`, `metadata`, and `options` are merged.
Endpoint returns non-`2xx` and failure behavior is `block`	Session stops before the assistant starts.
Endpoint returns non-`2xx` and failure behavior is `allow`, `none`, `do_nothing`, or `do-nothing`	Session continues unauthenticated. Returned overrides are not applied.

Use block for login, subscription, tenant authorization, compliance, or account access checks. Use allow only when authentication is being used as optional personalization or lookup.

Conditions

Conditions let one assistant use authentication only for specific channels or session types. The supported condition keys are:

Key	Allowed values
`source`	`all`, `sdk`, `web_plugin`, `debugger`, `phone`, `phone-call`, `whatsapp`
`mode` or `conversation_mode`	`all`, `text`, `voice`, `audio`
`direction`	`both`, `all`, `inbound`, `outbound`

If multiple rules are configured, all rules must match. If the condition is malformed, authentication is treated as not allowed and the session continues unauthenticated. Example condition for inbound phone voice sessions:

[
  {
    "key": "source",
    "condition": "=",
    "value": "phone"
  },
  {
    "key": "mode",
    "condition": "=",
    "value": "voice"
  },
  {
    "key": "direction",
    "condition": "=",
    "value": "inbound"
  }
]

Dynamic AgentKit routing

Assistant authentication can return AgentKit metadata in options. Rapida merges it before opening the AgentKit stream, so your AgentKit backend or load balancer can use authenticated tenant or customer context.

{
  "options": {
    "agentkit.metadata": {
      "tenant": "acme",
      "customerTier": "enterprise",
      "authorization": "Bearer backend-session-token"
    }
  }
}

Use metadata for distribution labels such as tenant, region, or customerShard. Keep authorization checks in the AgentKit backend as well; load-balancer routing should not be the only security control. See Scale AgentKit backends for metadata-based routing examples.

Recommended setup

Area	Recommendation
Failure behavior	Start with `block` for any real access control.
Timeout	Start with `5000` ms, then lower after measuring endpoint latency.
Body mapping	Include all fields your auth service needs to make a deterministic allow/deny decision.
Required fields	Validate required fields in your auth service and return non-`2xx` when they are missing.
Overrides	Return only context the assistant, tools, AgentKit backend, routing layer, or logs need.
Secrets	Do not pass long-lived secrets from public clients. Use short-lived session tokens or server-side validation.

Experience

Use authentication overrides to adjust greeting and session behavior.

AgentKit

Run assistant logic in your own AgentKit backend.

Scale AgentKit backends

Route AgentKit traffic by authenticated metadata.

Telemetry

Export conversation events and runtime metadata.

Assistants

Knowledge

LLM Endpoint

Activity & Logs

External Integrations

Credentials

Workspace

Governance

Deployment Options

Configure in Rapida Console

What to configure

Request body mapping

Endpoint response

Failure behavior

Conditions

Dynamic AgentKit routing

Recommended setup

Experience

AgentKit

Scale AgentKit backends

Telemetry

​Configure in Rapida Console

​What to configure

​Request body mapping

​Endpoint response

​Failure behavior

​Conditions

​Dynamic AgentKit routing

​Recommended setup

​Related

Experience

AgentKit

Scale AgentKit backends

Telemetry

Configure in Rapida Console

What to configure

Request body mapping

Endpoint response

Failure behavior

Conditions

Dynamic AgentKit routing

Recommended setup

Related