{"id":13764783,"url":"https://github.com/ObjectIsAdvantag/webex-guestissuer","last_synced_at":"2025-05-10T20:31:06.626Z","repository":{"id":55369337,"uuid":"136010734","full_name":"ObjectIsAdvantag/webex-guestissuer","owner":"ObjectIsAdvantag","description":"CLI to generate Persistent Guests for Webex APIs, SDKs and Widgets","archived":false,"fork":false,"pushed_at":"2022-12-22T13:47:19.000Z","size":34,"stargazers_count":5,"open_issues_count":3,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T22:56:15.192Z","etag":null,"topics":["cisco-webex","cli","guest-issuer","webex-teams"],"latest_commit_sha":null,"homepage":"https://developer.webex.com/guest-issuer.html","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ObjectIsAdvantag.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-04T10:42:48.000Z","updated_at":"2023-02-13T10:22:19.000Z","dependencies_parsed_at":"2023-01-30T10:30:55.211Z","dependency_job_id":null,"html_url":"https://github.com/ObjectIsAdvantag/webex-guestissuer","commit_stats":null,"previous_names":["objectisadvantag/guestissuer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObjectIsAdvantag%2Fwebex-guestissuer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObjectIsAdvantag%2Fwebex-guestissuer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObjectIsAdvantag%2Fwebex-guestissuer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ObjectIsAdvantag%2Fwebex-guestissuer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ObjectIsAdvantag","download_url":"https://codeload.github.com/ObjectIsAdvantag/webex-guestissuer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253480381,"owners_count":21915246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cisco-webex","cli","guest-issuer","webex-teams"],"created_at":"2024-08-03T16:00:28.656Z","updated_at":"2025-05-10T20:31:05.548Z","avatar_url":"https://github.com/ObjectIsAdvantag.png","language":"JavaScript","funding_links":[],"categories":["Developer Tools"],"sub_categories":["Web SDK \u0026 Widgets samples"],"readme":"# CLI to generate JWT and access tokens for Webex 'Permanent Guest'\n\n'Guest Issuer' applications allow guests (aka, non Webex users) to persistently use the Webex cloud platform through the Webex SDKs and Widgets. Check the [online documentation for details](https://developer.webex.com/guest-issuer.html).\n\nThe `guestissuer` command line interface (CLI) helps generate Guest tokens for 'Guest Issuer' applications.\n\nTo use the tool, you'll first need to create a 'Guest Issuer' application from [Webex for Developers portal](https://developer.webex.com/add-guest.html), and fetch your 'Guest Issuer' application's identifier and secret.\n**Note that you need a Webex PAYING account to create 'Guest Issuer' applications.**\n\n\n## Quick Start\n\nTo generate a Guest token, type the commands below in a terminal:\n\n_Note for Mac/Linux users: add `sudo` before each of the `npm install` commands below._\n\n```shell\n# Install the CLI\nnpm install guestissuer -g\n\n# Create a JWT Guest token with the specified user info (expires in 90 minutes by default)\nguestissuer create \u003cuserId\u003e \u003cuserName\u003e -i \u003cissuerAppId\u003e -s \u003cissuerAppSecret\u003e [-d \u003cexpirationDelay\u003e]\n\n# Fetch an access token for the Guest user (valid for 6 hours)\nguestissuer login \u003cguestToken\u003e\n```\n\n\nYou can even get there quicker with the `quick` command:\n\n```shell\n# Install the CLI\nnpm install guestissuer -g\n\n# Create a Guest token, and fetch an access token right away (valid for 6 hours)\n# Here, the JWT guest token is volatile (neither stored, not returned)\nguestissuer quick \u003cuserId\u003e \u003cuserName\u003e -i \u003cissuerAppId\u003e -s \u003cissuerAppSecret\u003e\n```\n\n\n\n## Detailled instructions\n\nTo install the `guestissuer` CLI, type:\n\n    ```shell\n    npm install guestissuer -g\n    ```\n\n\nTo create a JWT 'Guest token' for a 'Guest' user (non Webex users), type:\n\n    ```shell\n    guestissuer [create] \u003cuserId\u003e \u003cuserName\u003e -i \u003cissuerAppId\u003e -s \u003cissuerAppSecret\u003e [-d \u003cexpirationDelay\u003e]\n    ```\n\n    Where:\n        - `userId` is a user identifier unique to your 'Guest Issuer'. This identifier is used by the Webex cloud platform to persist user data among sessions. Understand: if another token gets generated with the same 'userId', the Guest user interacting with that token will see Spaces, Messages, and inherit Memberships from previous Webex interactions for this 'userId',\n        - `userName` is used to identify the user in Webex spaces,\n        - `expirationDelay` should be specified in seconds, defaults to 5400s (90min) from now.\n        - the `issuerAppId` and `issuerAppSecret` tie to the 'Guest Issuer Application' created from the [Webex for Developers portal](https://developer.webex.com/add-guest.html).\n    \n    Example (with verbose debugging info):\n\n    ```shell\n    DEBUG=guest*  guestissuer create \"123\" \"Stève\" -i Y2lz...VzLMDY -s AMx/FPI...NABzD6o=\n        guest arguments successfully checked +0ms\n        guest successfully built Guest token: BDmh0rgbcVMfpklnyWfurxX5Y... +59ms\n        guest Guest token is valid till XXXXX +1ms        \n    eyJhbGciOiJSUzI1NiJ9.eyJtYWN...uNDU1WiJ9.berce_d8vrRw6vDI....nMAlnYNj-f921mcqU\n    ```\n\n    Note that:\n        - instead of passing them through command line parameters, you can alternatively specify the 'Guest Issuer Application'  identifier and secret via environment variables `ISSUER` and `SECRET` \n        - the `create` command is the default's for guestissuer. You can omit it as in `guestissuer \"123\" \"Stève\" -i Y2lz...VzLMDY -s AMx/FPI...NABzD6o=`\n        \n\nOnce you've got a JWT 'Guest token', you'll need to fetch an access token (valid for 6 hours).\n\n    ```shell\n    guestissuer login \u003cguestToken\u003e\n    ```\n\n    Note that:\n       - the command uses the Webex API 's /jwt/login endpoint behind the scene.\n       - the fetched accessed token is valid for 6 hours\n\n\nTo quickly check the data contained in a JWT token (guest or access token):\n\n    ```shell\n    guestissuer verify --jwt \u003ctoken\u003e\n    ```\n\n\nTo quickly the Person behind an access token (equivalent tp a GET /people/me request):\n\n    ```shell\n    guestissuer verify --access \u003caccess_token\u003e\n    ```\n\n\n### Guest tokens\n\nGuest tokens have a JWT format, and are signed with your 'Guest Issuer Application' secret so that Webex can be assured of its origin.\nIt contains an expiration date so that Webex will refuse to generate access tokens - via the /jwt/login endpoint - after the expiration date.\n\n**Example of Guest token**\n\n```\neyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJuYW1lIjoiU3TDqHZlIiwiaXNzIjoiWTJselkyOXpjR0Z5YXpvdkwzVnpMMDlTUjBGT1NWcEJWRWxQVGk4ek9URTRPR00zTWkwd01ESTVMVF EzWVRRdFlqQXlOUzAxT0dFd1kyRTNORFZrTURZIiwiZXhwIjoxNTE3MDczMDE5fQ.imX0LgZ6LT-xlT3A6mzF5gyGN0S2ty2aUyjTM35E8y4    \n```\n\nNote that the Guest token also has a JWT format.\nIf you decode it, you'll discover its contents.\nGo to https://jwt.io to decode it, or simply type: `guestissuer verify --jwt \u003cguest_token\u003e`\n\n**Decoded Header Section**\n\n```json\n{\n  \"alg\": \"HS256\",\n  \"typ\": \"JWT\"\n}\n```\n\n**Decoded Data section**\n\n```json\n{\n  \"sub\": \"123\",\n  \"name\": \"Stève\",\n  \"iss\": \"Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8zOTE4OGM3Mi0wMDI5LTQ3YTQtYjAyNS01OGEwY2E3NDVkMDY\",\n  \"exp\": 1517073019\n}\n```\n\n\n### Retreiving API access tokens for 'Guest' users \n\nThese tokens are generated from 'Guest tokens' by invoking Webex API 's /jwt/login endpoint\nThey give access to the Webex API, SDKs and Widgets under the identity of the 'Guest' user.\n\nTo test an access token for a user, reach to the [GET /people/me](https://developer.webex.com/endpoint-people-me-get.html) resource, paste the access token and run the request.\nAlternatively, you can type: `guestissuer verify --access \u003caccess_token\u003e`\n\n    Example of Person details for an access token attached to a Guest user:\n\n    _Note that the person type is `bot` and the email is formed from `\u003cuser_id\u003e@\u003cdecoded-org\u003e`_\n\n    ```json\n    {\n        \"id\": \"Y2lzY29zcGFyazovL3VzL1B....Q5YzgtODAzMS02OTY1NWM4MGI3Njc\",\n        \"emails\": [\n            \"123@39188c72-0029-47a4-b025-58a0ca745d06\"\n        ],\n        \"displayName\": \"Stève\",\n        \"avatar\": \"https://00792fd90955bc2.....da928cc2123a400b.ssl.cf1.rackcdn.com/default_machine~80\",\n        \"orgId\": \"Y2lzY29zcGFyazovL3VzL09SR0FOSVp...DI5LTQ3YTQtYjAyNS01OGEwY2E3NDVkMDY\",\n        \"created\": \"2018-01-27T16:13:25.558Z\",\n        \"type\": \"appuser\"\n    }\n    ```\n\nNote that the issued token also has a JWT format.\nIf you decode it, you'll discover its structure.\nGo to https://jwt.io, or simply type: `guestissuer verify --jwt \u003ctoken\u003e`\n\n\n**Decoded Header Section**\n\n```json\n{\n  \"alg\": \"RS256\"\n}\n```\n\n**Decoded Data section**\n\n```json\n{\n  \"machine_type\": \"appuser\",\n  \"expiry_time\": 1517095624105,\n  \"user_type\": \"machine\",\n  \"realm\": \"2a9e1....ad3c991b1b5\",\n  \"cis_uuid\": \"8dcc341a...55c80b767\",\n  \"reference_id\": \"b4f77f9.....204f3daac88\",\n  \"iss\": \"https://idbroker.webex.com/idb\",\n  \"token_type\": \"Bearer\",\n  \"client_id\": \"C311772...1c2c82784a1f2975c\",\n  \"token_id\": \"AaZ3r0t...0YzIxYzliZGE0NDNiOGRiYzctMmI1\",\n  \"private\": \"eyJhbGciOiJkaXIiL...Tx45V0-PA\",\n  \"user_modify_timestamp\": \"20180127172701.477Z\"\n}\n```\n\n\n### Tip : Adding a 'Permanent Guest' to a space\n\nThe general use case for \"Permanent Guest\" is to call an existing Webex user, and create a space and add Bots or Webex users to the space.\n\nSometimes, you may be interested to add a 'Permanent Guest' to an existing space (or newly created space).\nYou'll hit a difficulty here since 'Permanent Guest' cannot be reached via their Webex email.\nSimply use the `personId` in the [POST /membership - Create a membership](https://developer.webex.com/endpoint-memberships-post.html) resource.\nNote that you can get the Webex `personId` of a \"Permanent Guest\" through a [GET /people/me](https://developer.webex.com/endpoint-people-me-get.html) request issued with the \"Permanent Guest\" access token.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FObjectIsAdvantag%2Fwebex-guestissuer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FObjectIsAdvantag%2Fwebex-guestissuer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FObjectIsAdvantag%2Fwebex-guestissuer/lists"}