anchorOverview

As a Webex developer, you can create Integrations to interact with Webex on behalf of a user. You can also create Bots that act as an independent user representing your service or product. But, what if you want to interact with users who do not have a Webex account? These users may be visitors to a website who you'd like to message with over Webex. Or they may be customers in a store you’d like to have a video call with. These guest users can interact with regular Webex users via tokens generated by a Guest Issuer application.

Guest users of Webex authenticate with guest tokens. Guest tokens use the JSON Web Token (JWT) standard to create and share authentication credentials between our SDKs & Widgets and the Webex REST API. These tokens are exchanged for an access authentication token which can be used for a limited time, and limited purpose, to interact with regular Webex users.

Each guest token should be associated with an individual user of your application. Their activity within Webex, such as message activity or call history, will persist, just like a regular Webex user. While guest users can interact with regular Webex users, they are not allowed to interact with other guests.

anchorGuest Issuer App

Before you can create guest tokens, you will need to create a new Guest Issuer application in My Webex Apps for use with your app. This application type will provide you with a Guest Issuer ID and a Secret. These two parameters will be used to generate guest tokens. Only paid Webex subscribers may create Guest Issuer applications.

After creating a Guest Issuer application, the secret will only be shown once. Keep this shared secret safe, as you would with any other sensitive piece of information such as a password. If you need to regenerate the secret for any reason, the prior secret will be immediately invalidated.

anchorGenerating Guest Tokens

Once you create a Guest Issuer app in My Webex Apps, you can create guest tokens to authenticate guest users and perform actions against the Webex REST API.

Guest tokens use the JSON Web Token (JWT) standard. JSON Web Tokens are composed of three parts, separated by a dot (.):

• Header
• Payload
• Signature

Header

{
  "typ": "JWT",
  "alg": "HS256"
}

The header describes the token:

The header is base64url encoded to create the first part of the token.

Payload

{
  "sub": "guest-user-7349",
  "name": "Guest User's Display Name",
  "iss": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE",
  "exp": "1511286849"
}

The payload contains the claims for the token. The Webex REST API expects the following claims:

The payload is then base64url encoded to create the second part of the token.

Signature

To create the signature, the encoded header and payload, along with the secret (provided when the app is created) are combined and signed using the algorithm specified in the header. For example:

var encodedData = base64urlEncode(header) + '.' + base64urlEncode(payload);
HMACSHA256(encodedData, 'secret');

After creating the signature, all three parts are combined to create the guest token:

ABC123.DEF456.xd84f342d2

The secret provided when the app is created is base64-encoded. Certain JWT libraries require a decoded secret to generate the token. For example, to sign a token when using the jsonwebtoken NPM package, create a new Buffer to decode the secret when creating the signature:

var jwt = require('jsonwebtoken');

var payload = {
  "sub": "guest-user-7349",
  "name": "Guest User's Display Name",
  "iss": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE"
};

var token = jwt.sign(
  payload,
  Buffer.from('a71939434514ab0823ed06a63fc24715cef62b8d7428866d91037f90d9cce1f3', 'base64'),
  { expiresIn: '1h' }
);

More Resources

JWT.io provides an interactive JWT debugger and a great list of libraries which can be used to generate JSON Web Tokens in different languages. More tools are also available to help generate guest tokens.

anchorUsing Guest Tokens

Once you've created a guest token, you can use it to authenticate as a guest user and interact with Webex users. Several functions in the Webex SDKs can be performed after authenticating with a guest token. If you need to use the Webex REST API directly, you'll need to exchange it for an access token. See below for a few examples of using a guest token with our SDKs and the API.

After a guest user is authenticated, a Webex guest account is created, and they can then perform actions just like regular users. There are a few important differences from regular users to keep in mind:

• Webex accounts for guest users are created only after authenticating with a guest token; accounts cannot be created manually
• Guest users may only interact with regular users; they cannot interact with other guest users
• Guest users will not have a valid email address associated with their account—use their individual personId with any activities that require the identification of a specific user

When using guest tokens with the SDKs and Widgets, session management is handled automatically. If the guest token is exchanged for an access token, your application will need to handle guest user sessions. See Using the Access Token below for more information.

Using with the Browser SDK

The Browser SDK accepts guest tokens when authorizing a user. To initialize and authenticate with a guest token instead of using a grant flow, use the requestAccessTokenFromJwt function. The function's input is an object with a property of "jwt" that's set to a valid guest token. For example, {jwt: "your.guest.token.here"}. This function exchanges the guest token for an access token and authenticates the session using that access token.

var Webex = require('webex');
var webex = Webex.init();

var token = 'your.guest.token.here';
// wait until the SDK is loaded and ready
webex.once(`ready`, function() {
    webex.authorization.requestAccessTokenFromJwt({jwt: token})
      .then(() => {
        // the user is now authenticated with a guest token (JWT)
        // proceed with your app logic
      })
});

Using with the iOS SDK

To initialize and authenticate the iOS SDK with a guest token, provide it as a parameter when authorizing the user:

let authenticator = JWTAuthenticator()
let spark = Spark(authenticator: authenticator)

if !authenticator.authorized {
    authenticator.authorizedWith(jwt: myJwt)
}

Using with the Widgets

To use the Widgets with a guest token, simply instantiate the widgets with guest token. For example, here's how you would use a guest token with the Space Widget:

var widgetEl = document.getElementById('my-webexteams-widget');
// Init a new widget
webex.widget(widgetEl).spaceWidget({
  guestToken: 'GUEST_TOKEN',
  destinationId: 'SPACE_ID',
  destinationType: 'spaceId'
});

To quickly test a guest token with the widgets, use the Widgets Demo.

Exchanging for an Access Token

The SDKs handle the guest token exchange and authentication for you, but if you aren't using an SDK, or need more control over the authentication process, you can use the REST API to exchange a guest token for an access token. You can then use the access token to make API requests like you would with a bot token or integration token.

To exchange the guest token for an access token, make an HTTP POST to a special endpoint with the guest token in the Authentication header:

Example Request

curl --request POST \
  --header "Authorization: Bearer GUEST_TOKEN" \
  https://webexapis.com/v1/jwt/login

You will then receive the access token and an expiration time in seconds:

Example Response

{
  "token": "ACCESS_TOKEN",
  "expiresIn": "21599"
}

In this example, the access token will be valid for almost six hours. The expiration (exp) claim in the guest token will not affect this expiration time.

Using the Access Token

Once you have an access token, you can use it with the Webex REST API to perform actions as the guest user. For example, if your guest user is sending messages to Webex users, use the Messages API to send messages to them. The token will include the appropriate scopes for messaging, calling, and people.

When using access tokens, your application will need to manage guest user sessions. A refresh token is not provided after exchanging the guest token for an access token. If a session needs to continue past the expiration time of the access token, create a new guest token for the user and exchange it for a new access token.

For example, you can use the access token to fetch details about the guest user via the Get My Own Details endpoint:

Example Request

curl --request GET \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  https://webexapis.com/v1/people/me

Example Response

{
  "id": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS8wMDAwMDAwMC0xMTExLTIyMjItMzMzMy00NDQ0NDQ0NDQ0NDQ",
  "emails": [
    "00000000-1111-2222-3333-444444444444@appid.ciscospark.com"
  ],
  "phoneNumbers": [],
  "displayName": "Guest User",
  "nickName": "Guest",
  "avatar": "https://00792fd90955bc2b54b7-dde9bcd8a491bb35da928cc2123a400b.ssl.cf1.rackcdn.com/default_machine~80",
  "orgId": "Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wMDAwMDAwMC0xMTExLTIyMjItMzMzMy00NDQ0NDQ0NDQ0NDQ",
  "created": "2019-10-01T15:00:00.000Z",
  "status": "unknown",
  "type": "appuser"
}

Changing the Display Name

To change the display name of a guest user who has already authenticated, simply re-authenticate with a new guest token. Create a new guest token and change the name payload claim to the new display name. To ensure that this new guest token is associated with the same guest user, use the same unique user identification value for the sub payload claim. After authenticating via the API or with the SDKs with the new guest token, the guest user's display name will be updated.