How Do I Authenticate to use the Query Service API?

Dave Woodman

Updated June 13, 2023 21:13

Community moderator

How Do I Authenticate to use the Query Service API?

The credentials used to authenticate against the Assurance API are the same as your normal Vyopta user credentials.

Obtaining Authorization:

The API authentication is performed via OpenID, with the credentials being sent as an application/x-www-form-url-encoded payload to a POST request to https://login.vyopta.com/auth/realms/vyopta/protocol/openid-connect/token. The Content-Type header must be set, and a header with key of Host must also be set - this header takes a value of login.vyopta.com

The encoded payload contains the following key-value pairs:

grant_type which takes the value password
client_id, with value vyopta
username which is the vyopta user name
password - the vyotpa password

Upon successful authentication, a 200 response will be received with a JSON payload with the following schema:

{
  "access_token": string,
  "expires_in": int,
  "refresh_expires_in": int,
  "refresh_token": string,
  "token_type": string,
  "not_before_policy: long,
  "session_state": string,
  "scope": string
}

access_token	The token (beginning "eyJh") that can be used to access the API
expires_in	The period of time, in seconds, for which this token is valid (300)
refresh_expires_in	The period of valid time for the refresh_token. NOT IMPLEMENTED
refresh_token	A token to refresh the authentication. NOT IMPLEMENTED
token_type	The authentication token type. Will have value of "bearer"
not_before_policy	The start of signing key validity for the access_token
session_state	Session information
scope	The basis upon which the token was authenticated. Will have value of "email profile"

Once a token has expired, it is necessary to re-authenticate. Refreshing the session is not implemented.

An example response (abbreviated) can be seen here:

{
  "access_token":"eyJhb ... -Pdl31W5g",
  "expires_in":300,
  "refresh_expires_in":1800,
  "refresh_token":"ey J...-H5oAwI8",
  "token_type":"bearer",
  "not-before-policy":1533920635,
  "session_state":"dad914da-2d68-4202-a98a-146da4033e1e",
  "scope":"emailprofile"
}

Using the Access Token:

To use the token, add a HTTP header with key Authorization and a value comprised of the word Bearer, a single space and then the token.

It is worth noting that it is the developers responsibility to ensure that the token is within its period of validity.