Flex SDK authentication (public beta)

(new)

Public Beta

The Flex SDK is currently available as a Public Beta product and the information contained in this document is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products are not covered by a SLA.

(warning)

Not a HIPAA Eligible Service or PCI Compliant

The Flex SDK is not a HIPAA Eligible Service or PCI compliant and should not be used in workflows that are subject to HIPAA or PCI.

There are three options to authenticate the Flex SDK:

Option 1: Use SSO to authenticate (recommended)

You can authenticate using SSO:

1import { getAuthenticationConfig, getLoginDetails, createClient, exchangeToken } from "@twilio/flex-sdk";
2
3// Helper to fetch the active authentication configuration for an account
4async function getAuthConfig(accountSid: string) {
5  try {
6    const authConfig = await getAuthenticationConfig({ accountSid });
7    const activeConfig = authConfig.configList.find((config) => config.active);
8    if (!activeConfig) {
9      console.error('No active auth config found');
10      return;
11    }
12    return activeConfig;
13  } catch (err) {
14    console.error('Error retrieving authentication config:', err);
15  }
16}
17
18async function initializeFlexApplication(accountSid: string) {
19  const LOGIN_DETAILS_KEY = 'LOGIN_DETAILS';
20
21  // See if an auth code is present in the URL
22  const searchParams = new URLSearchParams(window.location.search);
23  const authCode = searchParams.get('code');
24
25  const storedLoginDetails = localStorage.getItem(LOGIN_DETAILS_KEY);
26
27  // If we have stored login details and an auth code, exchange it for an access token
28  if (storedLoginDetails && authCode) {
29    const loginDetails = JSON.parse(storedLoginDetails);
30    const authConfig = loginDetails.authConfig.ssoProfileSid;
31
32    const exchangeTokenConfig = {
33      code: authCode,
34      clientId: loginDetails.clientId,
35      codeVerifier: loginDetails.codeVerifier,
36      nonce: loginDetails.nonce,
37      state: loginDetails.state,
38      ssoProfileSid: authConfig?.ssoProfileSid || '',
39    };
40
41    const tokenRes = await exchangeToken(exchangeTokenConfig as any);
42    if (!tokenRes.accessToken) {
43      return;
44    }
45
46    const userOptions = {}; // Optional config options
47    return createClient(tokenRes.accessToken, userOptions);
48  }
49
50  // Otherwise, kick off the login flow
51  try {
52    const authConfig = await getAuthConfig(accountSid);
53    if (!authConfig) {
54      return;
55    }
56
57    const loginDetails = getLoginDetails({
58      clientId: authConfig.clientId,
59      ssoProfileSid: authConfig.ssoProfileSid,
60      redirectUrl: window.location.origin,
61    });
62
63    // Store login details for later use
64    localStorage.setItem(
65      LOGIN_DETAILS_KEY,
66      JSON.stringify({ ...loginDetails, ...authConfig })
67    );
68
69    // Redirect user to login page
70    window.location.href = loginDetails.loginUrl;
71  } catch (error) {
72    console.error('Initialization error:', error);
73  }
74}
75
76const accountSid = 'ACCOUNT_SID';
77initializeFlexApplication(accountSid).then((client) => {
78  console.log('FlexSDK Client:', client);
79  // Do something with the FlexSDK Client
80});
81

The authentication process involves these key components:

Login Details: Use the getLoginDetails function to retrieve the information needed for the Flex Client to start the login process with your Identity Provider (IdP).
Token Management: Refresh and validate tokens to maintain secure and continuous operation of your system.
Authentication Config: Fetch OAuth configurations to understand your setup and handle any additional parameters required for token exchange.
Flex Client: Create the Flex Client by passing in the token and user-specific configurations to set up your environment.

Customization

Depending on your specific requirements, you might need to adjust the optional userOptions provided to createClient for better logging, telemetry, and session management.

Error handling

It's important to build robust error handling to catch and respond to any issues that might arise during the initialization and operation process.

Integration

Integrate the provided methods into your Flex SDK application lifecycle to manage user authentication, token validation, and system setup effectively.

Option 2: Use a JWE token to authenticate

You can get the Flex authentication token from your authenticated Hosted Flex application.

The token is stored in the browser's local storage, and you can use it to initialize the FlexSDK client.

The JWE token in the browser's local storage.

The following would initialize Flex SDK and enable you to access the surface area of Flex.

1import { createClient } from '@twilio/flex-sdk'
2
3const client = await createClient("FlexToken");

Option 3: Build your own authentication

If you don't want to use an SSO solution, you can build your own authentication method.

To build your own authentication, you'll need to:

For authorization, use Basic Authentication, which is an authentication method that provides a username and password when a request is made. Use your AccountSid for the username, and your AuthToken for the password.

(warning)

Warning

Only use the following endpoints internally on the backend. For security reasons, do not expose your AuthToken in front-end applications.

Provision a user

To provision a user, replace {flex_instance_sid} in the command below with your Flex Instance SID (GOxxxxxxxxxxxxxxxxxxxxx). You'll find your Flex Instance SID in Console on the Flex Overview page.

1curl --location 'https://flex-api.twilio.com/v4/Instances/{flex_instance_sid}/Users/Provision' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: ••••••' \
4--data-raw '{
5"username": "user1",
6"email": "test@example.com",
7"full_name": "Foo Bar",
8"roles": ["agent"],
9"worker" : {
10    "attributes" : {
11        "channel.voice.capacity" : 10,
12        "language": "english, spanish",
13        "more.stringarray" : "more,more2"
14    }
15}
16}'

Sample response:

1{
2    "account_sid": "ACCOUNT_SID",
3    "created_date": "2025-03-25T15:09:41Z",
4    "deactivated": false,
5    "deactivated_date": null,
6    "email": "user@example.com",
7    "flex_team_sid": "FLEX_TEAM_SID",
8    "flex_user_sid": "FLEX_USER_SID",
9    "full_name": "Foo Bar",
10    "instance_sid": "FLEX_INSTANCE_SID",
11    "locale": null,
12    "roles": [
13        "agent"
14    ],
15    "teams": {
16        "team_member": null,
17        "team_owner": null
18    },
19    "updated_date": "2025-03-25T15:09:41Z",
20    "username": "user1",
21    "version": 0,
22    "worker": {
23        "worker_sid": "WORKER_SID",
24        "workspace_sid": "WORKSPACE_SID"
25    }
26}
27

Note the Flex User ID (FUxxxxxxxxxxxxxxxxxxxxx) as you'll use this later for token minting.

Fetch a user

To fetch the user you're authenticating, run the following command:

1curl --location 'https://flex-api.twilio.com/v4/Instances/{flex_instance_sid}/Users?Username=user1' \
2--header 'Authorization: ••••••' \

You can query users with the Username= query parameter and value, which is user1 in the previous example.

Sample response:

1{
2    "account_sid": "ACCOUNT_SID",
3    "instance_sid": "INSTANCE_SID",
4    "meta": {
5        "direct_token": true,
6        "list_key": "users",
7        "next_token": null,
8        "page_size": 1,
9        "previous_token": null
10    },
11    "users": [
12        {
13            "account_sid": "ACCOUNT_SID",
14            "created_date": "2025-03-25T15:09:41Z",
15            "email": "user@example.com",
16            "flex_team_sid": "FLEX_TEAM_SID",
17            "flex_user_sid": "FLEX_USER_SID",
18            "full_name": "Foo Bar",
19            "instance_sid": "INSTANCE_SID",
20            "locale": null,
21            "roles": [
22                "agent"
23            ],
24            "updated_date": "2025-03-25T15:09:41Z",
25            "user_sid": null,
26            "username": "user1",
27            "version": 1,
28            "workspace_sid": "WORKSPACE_SID"
29        }
30    ]
31}

Mint an authentication token

To mint an authentication token, update the {flex_instance_sid} and {flex_user_sid} values, then run the following command:

1curl --location 'https://flex-api.twilio.com/v4/Instances/{flex_instance_sid}/Users/{flex_user_sid}/Tokens' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: ••••••' \
4--data '{
5  "ttl":3600
6}'

Sample response:

1{
2    "access_token": "ACCESS_TOKEN",
3    "token_info": {
4        "account_sid": "ACCOUNT_SID",
5        "expiration": "2025-03-25T16:16:16Z",
6        "flex_instance_sid": "FLEX_INSTANCE_SID",
7        "flex_user_sid": "FLEX_USER_SID",
8        "identity": "user1",
9        "permissions": [
10            "FPN9999",
11            "FPN0000"
12        ],
13        "roles": [
14            "agent"
15        ],
16        "username": "user1"
17    }
18}