Require human approval with CIBA

(new)

Private Beta

Agent Identity is available as a Private Beta product, and the information contained in this document is subject to change. You acknowledge and agree that your use of Agent Identity is subject to the terms of the Services in Private Beta. Some features are not yet implemented and others may change before the product is declared as Generally Available. Private Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

Agents often act while the user isn't present, well after the user first grants access. For high-risk actions such as spending money or sharing data, you can require the user to approve the specific action before the agent proceeds. Agent Identity supports this with Client-Initiated Backchannel Authentication (CIBA), delivered over Twilio RCS and SMS channels.

CIBA separates the device that initiates an action (the agent) from the device where a person approves it (their phone), making asynchronous, out-of-band approvals possible.

How the approval flow works

Your resource server determines that an action needs human approval and challenges the agent.
The agent calls the Agent Identity backchannel authentication endpoint to start an approval request. Agent Identity records the request and returns a request identifier (auth_req_id) and an expiry window.
Agent Identity sends the approval request to the user over a Twilio channel, orchestrated through Twilio Verify.
The user approves or denies the request. Depending on the channel and the action, they either select a response in-channel or follow a link to a hosted approval screen.
Meanwhile, the agent polls the token endpoint with the auth_req_id. It receives an authorization_pending response until the user acts.
When the user approves, the token endpoint issues an access token to the agent, carrying the approved permission. Agent Identity records the decision.

Approval channels and modes

Agent Identity supports two approval modes:

Hosted approval screen: the message directs the user to a page on your domain that shows the full request and Approve and Deny actions. This is the most secure mode and the right choice for extremely sensitive actions, because the full context lives on a web page rather than in a message body.
In-channel approval over RCS: the user sees the request in the message and taps to approve or deny, using an RCS quick-reply action. This gives the lowest-friction experience for actions where the details fit in a short message body.

SMS is always available as a fallback when RCS isn't.

(warning)

Warning

Before Agent Identity can send an approval-request SMS or RCS message to an end user, you must have that user's opt-in consent to receive messages at the phone number stored on their identity record, in accordance with the Twilio Messaging Policy.

What you configure

Enable CIBA: turn CIBA on or off by enabling or disabling an alternate notification channel on the Notification Channels tab in the Agent Identity Console configuration page.
Verify service: provide information about your Verify service and associated templates. This Verify service is used to send CIBA requests across your account, and needs to be specific to Agent Identity. Don't use an already-configured Verify service you are using in production. Visit the Services page in the Verify section of the Twilio Console to create one.
Define approval actions: define which actions require approval using Rich Authorization Request types. See Authorize agents with scopes and Rich Authorization Requests.
Custom SMS templates (optional): if you'd like to customize the messaging your users receive via SMS, create custom templates through Twilio Support. Otherwise, Verify sends messages using the default SMS template, which does not need to be specified in the configuration screen. For example: {friendly_name} needs your approval. Click here to respond: {hosted approval link}
Custom RCS experience (optional): if you'd like to offer a custom branded rich card experience, configure a custom RCS template through Twilio Support. You also need to create an RCS sender in the Console under Communications > Numbers & senders > Overview > RCS, where you can configure branding, messaging, colors, and more. Otherwise, RCS messages use the default RCS template.

(warning)

Warning

If you create your own RCS sender, you need to configure custom routing rules via Twilio Support to send traffic using your sender instead of the default sender and to configure fallback behavior (which can be sent via the default SMS sender or your owned numbers). Configuring routing rules affects other Verify services in your account.