3.20.0

The Authentication REST API Interface defines the REST API interface which customers will need to implement in their own authentication system, if they would like to integrate their own user authentication system with ServiceMobility.

By implementing an API which matches the Authentication REST API Interface, customers can configure ServiceMobility (via the Entity System Configuration object) so that calls made to the Create JWT REST API are passed through to their own user authentication system, instead of using user authentication details stored in ServiceMobility.

On this page:

Related pages:

Create JWT REST API

Resource URL Summary

Create JWT Token

POST <REST Endpoint URI>

HTTP Headers

HTTP Header	Value
`Content-Type`	`application/json`

API Specifics

Create JWT Token

This REST API must authenticate user's credentials. If the credentials passed in are verified, then this API must return a valid JWT, which ServiceMobility will then use to allow access other REST APIs.

URL

POST <REST Endpoint URI>

HTTP Request Body

The HTTP will contain a valid Authentication Object.

HTTP Response

Response Codes

HTTP Code	Description
200	OK. Credentials were verified and a valid JWT was returned.
401	Invalid Logon.
500	Server error. An error occurred while processing the request. The HTTP response body should have more details as to the possible cause.

On success, an HTTP response code of 200 must be returned, and the response body must contain a valid JWT token.

Response Object Format

{
	"token": ""
}

Response Object Properties

Required properties are in bold.

Property Description

token

The token property, in the returned response will be used for all subsequent REST API calls. ServiceMobility supports the HMAC SHA256 hashing algorithm for the JWT token. The JWT token must include registered and optional private claims in the payload.

Header: Algorithm & Token Type

Claim	Description	Format
`alg`	Hashing Algorithm	`String ("HS256")`
`typ`	Type of the token	`String ("JWT")`

Payload: Data

Registered Claims

Claim	Description	Format
`exp`	Expiration Time	Number of seconds since Epoch (1970-01-01T00:00:00Z UTC) until the specified UTC date (and time).
`iat`	Issued At	Number of seconds since Epoch (1970-01-01T00:00:00Z UTC) until the specified UTC date (and time).

Private Claims (Optional)

Claim	Description	Format
`name`	Name for the authorized user requesting JWT token.	String
`email`	Email address of the user.	String
`expdb`	Expiry Dead Band. This private claim will allow a mobile worker to remain logged into the mobile application through the auto-login process even after the expiration of JWT token. The mobile application will not have ability to communicate with the back office when a mobile worker is logged with expired JWT.	Number of minutes