Guest Issuer Applications


As a Cisco Spark developer, you can create Integrations to interact with Cisco Spark 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 Cisco Spark account? These users may be visitors to a website who you'd like to message with over Cisco Spark. Or they may be customers in a store you’d like to have a video call with. These guest users can interact with regular Cisco Spark users via tokens generated by a Guest Issuer application.

Guest Users of Cisco Spark, also referred to as Persistent Guest users, 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 Cisco Spark API. These tokens are exchanged for an OAuth authentication token which can be used for a limited time, and limited purpose, to interact with regular Cisco Spark users.

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

Guest Issuer App

Before you can create Guest Tokens, you will need to create a new Guest Issuer application in My 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 Cisco Spark subscribers may create Guest Issuer applications.

The secret will only be shown once, when the application is first created. 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.

Generating Guest Tokens

Once you create a Guest Issuer app in My Apps, you can create Guest Tokens to authenticate guest users and perform actions against the Cisco Spark 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


  "typ": "JWT",
  "alg": "HS256"

The header describes the token:

typ The type of token. Must be JWT.
alg The hashing algorithm. Must be HS256.

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


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

The payload contains the claims for the token. The Cisco Spark API expects the following claims:

sub The subject of the token—a unique, public identifier for the end-user of the token. This claim may contain only letters, numbers, and hyphens. This claim is required.
name The display name of the guest user. This will be the name shown in Cisco Spark clients.
iss The issuer of the token. Use the Guest Issuer ID provided in My Apps. This claim is required.
exp The expiration time of the token, as a UNIX timestamp in seconds. Use the lowest practical value for the use of the token. This claim is required.

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


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:


The secret provided when the app is created is base64-encoded. Certain JWT libraries require a decoded secret to generate the JWT token. For example, to sign a JWT 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(
  Buffer.from('a71939434514ab0823ed06a63fc24715cef62b8d7428866d91037f90d9cce1f3', 'base64'),
  { expiresIn: '1h' }

More Resources provides an interactive JWT debugger and a great list of libraries which can be used to generate JSON Web Tokens in different languages.

Using Guest Tokens

Once you've created a guest token, you can use it to authenticate as a guest user and interact with Cisco Spark users. After a guest user is authenticated, a Cisco Spark 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:

  • Cisco Spark 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

Several of the Cisco Spark SDKs have the ability to authenticate a guest user with a guest token. You can also use the Cisco Spark API directly after authenticating the guest user. See below for a few examples of using guest tokens with the SDKs and the API.

Using with the Browser SDK

Initialize and authenticate with a Guest Token instead of using a grant flow:

// require and initialize the Cisco Spark SDK
var CiscoSpark = require('ciscospark');
var spark = CiscoSpark.init();

// wait until the SDK is loaded and ready
spark.once(`ready`, function() {
  if (spark.canAuthorize) {
    // the user is already authenticated
    // proceed with your app logic
  else {
      .then(() => {
        // the user is now authenticated with a JWT
        // proceed with your app logic

Using with the iOS SDK

Initialize and authenticate with a Guest Token:

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

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

Exchanging for an OAuth Token

After generating a Guest Token, it needs to be exchanged for an OAuth token for use by your application. To exchange the 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_ISSUER_TOKEN" \

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

Example Response

  "token": "AUTH_TOKEN",
  "expiresIn": "600"

Using the OAuth Token with APIs

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