App Verify API - Tutorial: JWT Service for App Verify API
In order to use App Verify API, you must set up and host a JSON Web Token (JWT) service that your mobile application can communicate with. Your mobile application calls the JWT service to request a security token. Telesign's verification server then uses the security token to validate your Customer ID and determine whether the token is associated with you.
NOTE:
You must have a JWT service if you are working with App Verify API.
This document provides general information about how to use JSON Web Tokens (JWT) to authenticate with the App Verify API service. If you want to see a complete walkthrough for how to create a JWT service, check out Implement a JWT Service.
Requirements
This section provides details about requirements for setting up your JWT service.
- You need to be able to store the XID, a unique reference ID you generate and associate with each transaction. The XID is discussed below in section External ID (XID) Token Parameter
- Follow the JWT formatting requirements presented in the JSON Web Tokens (JWT) section:
- Header
- Claims
- JWT Signature
- External ID (XID) Token Parameter
- Decide whether you will use a Telesign SDK or write your own code to retrieve a JWT token from your server. Using one of Telesign's SDKs is recommended as it is easier and more secure.
JSON Web Tokens (JWT)
The App Verify API service requires a JWT for authentication. Using JWTs mitigates the risk involved with storing sensitive Telesign API credentials in mobile applications.
A JWT has the following generic structure:
<base64-encoded header>.<base64-encoded claims>.<base64-encoded signature>
The following is an example of a typical JWT:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
Telesign requires that you implement JWTs that contain headers, claims, signatures, and the XID parameter as described in the sections below.
NOTE:
JWT field names are case sensitive and should be entered as lowercase in the following tables.
Header
This section describes how to implement the JWT header for your JWT token.
| Field | Type | Value | Required | Description |
|---|---|---|---|---|
| alg | String | HS256 | Yes | The algorithm used to encrypt the signature. For example, the string value "HS256", specifies that the JWT is a JSON Web Signature (JWS) that is message authentication coded (MACed) using the HMAC-SHA256 algorithm. |
| typ | String | JWT | Yes | The token type. Set this to the string value "JWT", to specify that the encoded object is a JSON Web Token (JWT). |
Claims
This section describes how to set up claims for your JWT token.
| Field | Type | Value | Required | Description |
|---|---|---|---|---|
| iss | String | Customer ID | Yes | The issuer's identity. This identifies that the organization is the source of the web token. |
| iat | Integer | NumericDate | Yes | The time that the token is issued. The value must be a Unix timestamp in seconds in NumericDate format (a JSON numeric value representing the number of seconds from 1970-01-01T0:0:0Z UTC until the specified UTC date/time). |
| exp | Integer | NumericDate | Yes | The time at which the token expires. This is the time after which the token is considered invalid and is therefore no longer usable. The time specified by iat must be earlier than exp. The value must be a Unix timestamp in seconds in NumericDate format. |
| xid | String | 36 CHAR UUID4 | Yes | A character string up to 36 characters (UUID4 format) to keep track of a transaction's status. |
JWT Signature
The JWT signature is produced by concatenating the Base64url encoded header with the Base64url encoded claims, and then signing the string using HMAC with SHA-256. The Telesign API key is Base64-encoded, so it needs to be decoded before signing it.
The following example shows an assigned Telesign API key:
Telesign API Key
Base64url encoded {HMAC-SHA256 of {Base64url encoded(Header) + "." + Base64url encoded(Claims)} using TeleSign issued API key}
For more information, see Requirements.
External ID (XID) Token Parameter
You pass a unique parameter called the External ID (xid) using the JWT in order to keep track of a transaction's status. It can be any character string up to 36 characters and must be in UUID4 format.
The recommended XID format is a 36 CHAR UUID4 value; for example:
XID Format Example
d01c6dbb-99d3-4335-8e22-11a50a2868f2
For more information, see the UUID4 definition on Wikipedia.
Resources
The App Verify API SDKs include sample code for a JWT service to help you implement your own token service. Access to the code is restricted based on whether you purchased the product or not. The App Verify API SDK was discontinued. If you want access to the GitHub repository for this product, speak with Support. The repository contains these things for a JWT Service:
- Python JWT Service
- Java JWT Service