Signing in with a session token

Request

To sign in with a session token, the client app should send a POST request to:

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

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.
  Each member of the array is a key/value pair in the following form:

  JSON

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

• One of the following:

  • For first-time signon, a deviceInformation block. See the Authentication Gateway Service (AGS) API documentation for details.

  • For subsequent (nth-time) signon, the clientId. (This is returned in the response on first-time signon.)

Once the app is signed in, it must re-authenticate periodically using the refresh token as explained in Re-authenticating using the refresh token.

Other arguments

None

Example

A POST request with this payload signs the client in (nth-time signon):

{
  "parameters": [
    {
      "name": "sessionToken",
      "value": "abc3fj6sdehd529ng33dg"
    }
  ],
  "clientId": "PUB_989"
}

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 201 status. The response body includes the access and refresh tokens.

A bad request returns an HTTP 400 status.

An unauthorised request returns an HTTP 401 status.

A forbidden request, one that fails authorisation, or one that is geo-blocked returns an HTTP 403 status.

If the specified <entity> does not exist, the request returns an HTTP 404 status.

Example

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

{
  "access_token": "eyJraWQiOiIyNTk2MjkiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50UHJvZmlsZUlkIjoiREVGQVVMVCIsInRlbmFudElkIjoibmFncmEiLCJmaWx0ZXJpbmdJbmZvcm1hdGlvbiI6e30sImJsb2NraW5nSW5mb3JtYXRpb24iOnt9LCJhY2NvdW50SWQiOiIxNjYzIiwidXNlcklkIjoiMTY2MyIsInZlciI6IjEuMCIsImdlb0Jsb2NrRXhlbXB0IjpmYWxzZSwicGFyZW50YWxDb250cm9sIjpudWxsLCJ0eXAiOiJEZXZBdXRoTiIsImp0aSI6IjQ3ODkwMjM0MjM3MTQwODk0NzgiLCJwbGF5b3V0RGV2aWNlQ2xhc3MiOm51bGwsImRldmljZUlkIjoiUFVCXzk4OSIsImV4cCI6MTY1NDg3NzA5MywiZml4ZWRfZXhwIjoxNjU3NDY1NDkzLCJvbk5ldHdvcmsiOnRydWUsInNlc3Npb25Db250cm9sIjp7Im1heFNlc3Npb25zIjozLCJzZXNzaW9uQ29udHJvbEVuYWJsZWQiOnRydWV9LCJiaWxsaW5nQ291bnRyeUNvZGUiOiJFbXB0eUNvdW50cnkifQ.y9tc1RZVS8un0N1oHHEnRAJeM6frgjlLrbzBgCXjqXk",
  "refresh_token": "eyJraWQiOiIyNTk2MjkiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2ZXIiOiIxLjAiLCJ0ZW5hbnRJZCI6Im5hZ3JhIiwic2Vzc2lvbkNvbnRyb2wiOnsibWF4U2Vzc2lvbnMiOjMsInNlc3Npb25Db250cm9sRW5hYmxlZCI6dHJ1ZX0sImFjY291bnRQcm9maWxlSWQiOiJERUZBVUxUIiwiZGV2aWNlSWQiOiJQVUJfOTg5IiwiZml4ZWRfZXhwIjoxNjU3NDY1NDkzLCJleHAiOjE2NTUwNDYyOTMsImFjY291bnRJZCI6IjE2NjMiLCJqdGkiOiI0Nzg5MDIzNDIzNzE0MDg5NDc4IiwidXNlcklkIjoiMTY2MyIsInR5cCI6IlJlZnJlc2hBdXRoTiJ9.ipL6gundtQ8Iai5qTXPpO6sviEAdLwP0Bt9aDO95yuc",
  "client_id": "PUB_989",
  "accountId": "1663",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_expires_in": 172800,
  "fixed_refresh_expires_in": 2592000
}

See also

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