Guest Issuer Applications

Overview

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 through Cisco Spark with users who do not have an account? These users may be visitors to a website who you'd like to chat with over Cisco Spark. Or they may be customers in a store you’d like to video chat with. These guest users interact with Cisco Spark users via Guest Issuer applications.

Guest Users authenticate via Guest Tokens, which use the JSON Web Token (JWT) standard to create and share authentication credentials between our SDKs & Widgets and the Cisco Spark API. JWT tokens are exchanged for authentication tokens 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 will not be able 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 Organization 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

Header

{
  "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.

Payload

{
  "sub": "Campaign-1",
  "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 description of the use of the token, for your classification.
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 Organization ID provided in My Apps.
exp The expiration of the token, in seconds. Use the lowest practical value for the use of the token.

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

Signature

To create the signature, the encoded header and payload, along with the shared secret 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

Using Guest Tokens

Using with the Browser SDK

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

var CiscoSpark = require('ciscospark');
var spark = CiscoSpark.init();

spark.once(`ready`, function() {
  if (spark.canAuthorize) {
    // your app logic goes here
  }
  else {
    spark.authorization.requestAccessTokenFromJwt({jwt})
  }
});

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" \
  https://api.ciscospark.com/v1/jwt/login

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.