Introduction

Bit6 uses JWT tokens to authenticate connections to the platform. With v2 we are standardizing the JWT claims format which simplifies the authentication and SDK configuration process. The JWT is generated either by:

• Customer's Application Server - outside of the Bit6 Platform, or
• Bit6 Auth helper service which is completely optional in v2

You can view JWT internals at jwt.io

JWT Credentials

You can obtain the key ID and secret for generating JWT tokens in Bit6 Console.

Token Format

Typically the JWT claims of the AccessToken will look like this:

{
  "aud": "https://api.dev.bit6.com/client/v1",
  "sub": "carol1/web-1",
  "grants": {
    "signal": true
  },
  "iss": "b234fdb83571400f9b62e204d735126e",
  "iat": 1490479599,
  "exp": 1490480108
}

• aud - the intended audience of this token. In our case it is Bit6 Client API endpoint URL.
• sub - the authenticated user's Identity and Device. / is a separator character.
• grants - describe the permissions and additional configuration options for the services the authenitcated enityt is authorized to use.
• exp - (optional) expiration time of the token - Unix epoch time

The AccessToken is the only required item to start using Bit6 Communication Services via Bit6 v2 SDKs or REST APIs.

App Server Integration

In many situations there is already an existing user management and authentication system in place. Bit6 can use it with a simple server-side integration. As the result a user signing into your app will be automatically authenticated in Bit6 platform and can immediately start using communication services.

Overall the process consists of the following steps:

1. User logs into your client-side app as usual
2. The app sends an authentication request to your application server
3. During that process, your server generates the standrad JWT token for Bit6 describing the user identity and permissions to use communication services
4. On the client side, you initialize Bit6 Services by providing them the JWT token
5. Internally, Bit6 will use the JWT you provided as-is

Own App Server

You will need to add a simple token generator to your app server code. Check out the following code samples (make sure to use next branch for now):

• Node.js - https://github.com/bit6/bit6-token-generator-node
• PHP - https://github.com/bit6/bit6-token-generator-php

We have deployed the sample app from the Node.js repo to make it easy to generate demo JWTs for client-side apps:

curl -X POST https://bit6-demo-token-svc.herokuapp.com/token \
    -d 'identity=bob1' \
    -d 'device=web1'

Here's Node.js sample code, also available here, that demonstrates the token generation process:

// Read Bit6 API Key ID and Secret from environment variables
const keyId = process.env.BIT6_KEY_ID;
const keySecret = process.env.BIT6_KEY_SECRET;
// Use TokenBuilder from
// https://github.com/bit6/bit6-token-generator-node/tree/next
const TokenBuilder = require('./lib/bit6-token-builder');
// User's identity - a text string that maps into the user object in your system
const identity = 'alice';
// User's deviceId - a unique identifier for the device to support multiple devices per user
const device = 'web1';
// Grant permissions to access Signal, Video, and Chat service
const grants = {
    chat: true,
    signal: true,
    video: true
};
// Expire the token in 1 hour (ttl is in seconds)
const ttl = 60 * 60;
// Build the token
const token = TokenBuilder.create()
    .key(keyId, keySecret)
    .access('client')
    .grants(grants)
    .identity(identity)
    .device(device)
    .ttl(ttl)
    .build()
// This is the token that you will use with Bit6 SDK
console.log('Token:', token);