Requesting a session token

Request

To request a session token to be used by a client app, the operator’s head-end service should send a POST request to:

https://<host>:<port>/ags/getSessionToken

Headers

• x-correlation-id – identifier for logging, to correlate messages across a call flow

• x-auth-service-id – the ID of the authentication (SSO) service to be used for authentication (mandatory).

  This comes from the authServiceName field (within availableServices) in the response to the service discovery request.

• nv-tenant-id – the tenant ID

Mandatory arguments

• x-auth-service-id – (in header) – see above

• parameters – an array of parameters. These are defined in the response to the GET /servicediscovery request.
  For example, for the STB QR code sign-in-scenario, this would be a JWT containing the account ID and tenant ID encoded using a shared secret.
  Each member of the array is a key/value pair in the following form:

  "parameters": [
    {
      "name": "<name>",
      "value": "<value>"
    }
  ]
  

Other arguments

None

Example

A POST request with this payload requests a session token:

"parameters": [
  {
    "name": "OperatorAuthToken",
    "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjcwNjQ2OTQ4LWQ2ZmItNGNlOC1hNDMzLTUyYTE0ZWUyZmEwYSJ9.eyJ0eXAiOiJHZXRTZXNzaW9uVG9rZW5BdXRoTiIsIk9wZkFjY291bnRJZCI6IlNlc3Npb25Ub2tlblNpZ25PbkFjY291bnQtMDAwMSIsIk9wZlRlbmFudElkIjoibmFncmEiLCJleHAiOjE3MzUwODQ4MDAsImF1ZCI6ImFncyJ9.yMwK-RJLh_nUeJPuoVtrfP8ol-sRuvO4dsy0QmRNzS8
  }
]

Note that the contents of the parameters block are provider-/customer-specific and are enumerated in the discovery block.

Response

A successful request returns an HTTP 200 status.

A bad request returns an HTTP 400 status.

An unauthorised request returns an HTTP 401 status.

A forbidden request returns an HTTP 403 status.

Example

The body of the response to a request that returns a 200 status looks like this:

{
  "sessionToken": "abc3fj6sdehd529ng33dg"
}

See also

For full details of this API, see the Authentication Gateway Service (AGS) API documentation.