anchorOverview

Service App Guest Creation API reference.

As a Webex developer, you can create Integrations to interact with Webex on behalf of a user. You can also create Bots that represent your service or product as an independent user. 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 Service App with the scopes guest-issuer:read and guest-issuer:write.

Guest users of Webex authenticate with guest tokens. These tokens follow the familiar, regular Bearer token standard - they are Access Tokens`, and are used to create and share authentication credentials between our SDKs & Widgets and the Webex REST API. They have a limited lifetime and limited purpose in order 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 it does for a regular Webex user. While guest users can interact with regular Webex users, they are not allowed to interact with other guests, with approved exceptions via a special license.

anchorService App Guest Creation

Before you can create guest tokens, you will need to create a new Service App in My Webex Apps for use by your system. Make sure you have, at a minimum, the guest-issuer:write and guest-issuer:read scopes selected which are used for guest management. Only paid Webex subscribers may create guests.

This Service App must be approved by an admin in Control Hub. To that end, you will need to submit your app for admin approval by an Full Admin within your organization. Or, if you want to create guests for other organizations, you will need to submit your Service App to AppHub. Do note, though, that Guests are always created in their own independent organization that has little relationship to the organization of the Service App or the organization of the approver.

For details on the approval process and subsequent retrieval of the Access Token and Refresh Token, please see the Service App Guide

anchorGenerating Guest Tokens

Once you have created a Service App with guest-issuer:write and guest-issuer:read scopes in My Webex Apps, have it approved by a full admin, and have the Service App Access Token in hand you can create guest tokens to authenticate guest users and perform actions against the Webex REST API.

In a single API call to /guests/token, you can create a guest, refresh the token or switch the guest display name according to the payload supplied.

Authorization

To authorize your guest creation call, you must use the Access Token of the Service App. Remember, the Service App manages the guests. Also, if you want to use the developer portal Try it mode, you need to unclick the Use personal access token toggle and instead copy the Service App Access Token into the Authorization field.

Payload for Guest Creation

To create a guest, you only need to provide two fields in your POST API call. A free-form string identifier that uniquely identifies the guest in your system and a display name shown in Webex Applications, SDKs, and Widgets.

POST PAYLOAD

{
  "subject": "My5thPerson",
  "displayName": "King Ralph the 5th",
}

Response

{
"id": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS8wZmE2NjgwZi01NWIyLTRkYzgtYjAzMC0xZWI0MzI4Y2MxYTg",
"subject": "My5thPerson",
"displayName": "King Ralph the 5th",
"email": "bf2936d4-40b6-3800-8562-5341c9ecc482@appid.ciscospark.com",
"accessToken": "eyJhbGciOiJSUzI1NiJ9.eyJtYWNoaW5lX3R5cGUiOiJhcHB1c2VyIiwiY2x1c3RlciI6IlBGODQiLCJwcml2YXRlIjoiZXlKamRIa2lPaUpLVjFRaUxDSmxibU1pT2lKQk1USTRRMEpETFVoVE1qVTJJaXdpWVd4bklqb2laR2x5SW4wLi5INjRvRFZVcFBRYVR5b1FwS2xjNFR3Lm0xVGFwMnlUTXFIQTNmdkpPQ1ZsZ1ZFUmx1NER5Q3VuYXdtWGRXbl9TNDFVTDZ4SUZTYXYzeUdxZ0tMVWxxT25VSlJMTzdtdDg4T01YMDJZLWcyYlFmY05BTm9rWTN0RE1neGloMEl4OFR3YlR0bWlrMnFGUkZiMlVDYldEQVFsN0ZERHFweGdTREt3N1FlWmhkeEhacEp3U0FzdzE2bG12ZjktREJEYnRMRVYyV3JoSm1RckY4U0c5dnZ0UFRwSm9NcFRNYXZid3lKV1FPNW02UUt1Z1RmYnp4Y2dGZ0xDTjh3NFQ5dXc0a0RacTkxMVZfak5vZDZTaGM2YVhPRFVSS09ianAtYzJJQTg0ZkI3dU9qTVBKS3pSdTNTR1dxd1JqMmV3cC1wdjJTTEgzV0hZMjRnVXFqYnFndHM2MHZ1T0J2dGIzdUlnNGpPQ3lKR25pRkxmblFiQXlzMmxXZ25jT0ZROWRMcnI0N3RDVktHZHVzQ1NIb1FaMWphMDlUWFJWRkdOb1V4Rjk4M1h6VmEyWURtLWF0eGoxQTFReVRrQUFaQ2hLNmp2N0VObU5Oakw3ZTRGUUQxWUl1ZWdxVUp3dTM4UzRRaFo0SV94bXlMSWg5UFdHRmpaUWwtTjJLSEtpM3hObXhodVFkZzlCNndDM0x3QnBjY3diSmRBRF9tdHJmVVlLYUNOMDQ4VklJQ2kwVmN1NGp0cjVsd2lfVGdXNUZVTXJwWUdwcTRzNEZGVFp4eEs3Q2ZNOXZxeWpoSU9nbEJSc2xpLVM2eWZLeEFOQ1pqX3h3bFRwZ0FCUFBIR1FuT2NPbWVCMEQwYTZSdTQtdW9RMXlaT3dPZE9JemcuOGVFX3pjMllGZ1BjR3JfUGVvYk5BUSIsInJlZmVyZW5jZV9pZCI6ImYwNTBjMDQzLTMyNTAtNDU2Zi1iMzI3LWJmYzM4YzEzNjlhYyIsImlzcyI6Imh0dHBzOlwvXC9pZGJyb2tlci53ZWJleC5jb21cL2lkYiIsInRva2VuX3R5cGUiOiJCZWFyZXIiLCJjbGllbnRfaWQiOiJDMzExNzcyM2EwYTRjOTg1YThiZDZkZGE3NmY3NzY2YzUxMzI0YjZmNDFiZjRmZWYxYzJjODI3ODRhMWYyOTc1YyIsInVzZXJfdHlwZSI6Im1hY2hpbmUiLCJ0b2tlbl9pZCI6IkFhWjNyME1EaGxPV1JrWVRndE56TTROQzAwWlRBMkxXRXlNbVl0TUdGaVpqbGpNbU0xTnpSaE56Z3lZVFEwT0dRdFpXWXkiLCJ1c2VyX21vZGlmeV90aW1lc3RhbXAiOiIyMDI0MDEzMTAwMDAwNS4xODFaIiwicmVhbG0iOiI3YjhkZDBlMi1kMDU1LTQzNzYtYjgwNC1kZDM4MTYyNDY5YTciLCJjaXNfdXVpZCI6IjBmYTY2ODBmLTU1YjItNGRjOC1iMDMwLTFlYjQzMjhjYzFhOCIsImV4cGlyeV90aW1lIjoxNzA2NzI0MDA0Mjc3fQ.dDghi4jYhHwMDjkc71GvocQImlY6YOY5ULLirRLFMxJB24O9A5GE81wAbEUGkE0QgK_1pXOeP-vifpEjpWWjJ9uvpx7_EEm9tIQEmcQALy9bbzd2mkT_lnG2oemPcKpD7EKxvvJvgnlOutZLxmPtSkItrgNdTcexpnziFqmqQJJTNvHehutKhudW_HzBA10gotzlehQ0evIi4-ZiloPE6XmAdNK-fJN4AydSkWcu1BA1zcpXT1GwiT6u0X_B_ujqVCUGYZKodBIRNB_r38ON6MSMWQMy_hZBQA5zlb0mz5TB6lYlzDej8Ql2Aal7MgGklHeLzZfxUY7dG4broCRjoQ",
"expiresIn": 64799
}

The API response contains the accessToken that you use in REST API calls and SDK invocations. The fields are described in detail in the API reference.

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.

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": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS8yNDAxNjk3NC1kMzEzLTRhNzctOTQ2MS0zYjRhZjU0MjI4OWY",
"emails": [
    "498fb162-6739-3513-8f68-349ef6359b4f@appid.ciscospark.com"
],
"phoneNumbers": [],
"displayName": "King Ralph the 4th",
"nickName": "King",
"userName": "498fb162-6739-3513-8f68-349ef6359b4f",
"avatar": "https://avatar-prod-us-east-2.webexcontent.com/default_machine~80",
"orgId":"Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi83YjhkZDBlMi1kMDU1LTQzNzYtYjgwNC1kZDM4MTYyNDY5YTc",
"created": "2024-01-30T23:55:27.425Z",
"status": "unknown",
"type": "appuser"
}

The guest email is synthetic and cannot be used to email the guest. The orgId is the guest organization ID. All guests are created in their own independent organization.

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

anchorRefresh the Guest Token

If your guest Access Token did expire and you want to keep the guest, you can create a new one by doing the POST to /guests/token with an existing subject. If the old token has life left, it won’t be revoked. Each user in Webex can have no more than 750 tokens, and this applies equally to guests.

anchorChange the Guest Display name

If you want to change your guest displayName, you do the POST to /guests/token with an already used subject and the new displayName. Remember that most Webex Applications retain history. So if you change the displayName between users but keep the subject, they may potentially see their respective space or call history.

To change the display name of a guest user who has already authenticated, simply re-authenticate with a new guest token. After authenticating via the API or with the SDKs with the new guest token, the guest user's display name will be updated.

anchorNumber of Guests Created

If you want to check the number of guests you have created, you can use the /guests/count endpoint. It returns an integer, not a JSON object, in the response.

anchorTips

Guests are created in their own organization for security purposes. While the guest id is a personId, the Service App and you as an admin cannot delete that guest. The Service App or admin cannot delete authorizations. Guest tokens age out on their own, and there is no limit to the number of guests. Contact Support if you need to delete guests.

anchorUsing Guest Tokens

Once you've created a guest access token, you can use it to authenticate as a guest user and interact with Webex users. The Webex SDK and WEBEX REST APIs accept the guest Access Token. See below for a few examples of using a guest token with our SDKs and the API.

When a guest token with a new subject is retrieved, the guest is created, and the guest can then perform actions just like regular users, albeit with limited scope. There are a few important differences from regular users to keep in mind:

• You can only create the guest implicitly by retrieving the token. You cannot use the /people API or Control Hub.
• Guest users may only interact with regular users; they cannot interact with other guest users
• Guests now have a personId and synthetic email that you can use in API calls.

Session management is handled automatically when using guest tokens with the SDKs and Widgets.

Using the SDKs

To use the guest accessToken with the SDKs, all you need to do is pass it in the init function.

 webex = window.webex = Webex.init({
    config: generateWebexConfig({}),
    credentials: {
      access_token: accessToken
    }
  }); 

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