Authentication

To be granted access to its functions, all requests made to the API must include a valid access token in a special HTTP header. This token identifies a user or organization, cannot be replicated or forged, and expires after a certain amount of time. Vathos provides access via a standardized Single Sign-on (SSO) service via the OpenID Connect protocol. All information necessary for authentication with an OpenID Connect client (e.g., in JavaScript) can be queried from the public service discovery endpoint. Without a dedicated client, a token is obtained with a single HTTP request as described in the following sections.

User tokens

Users who are natural persons require four different credentials for authentication (grant type "password"):

a client ID,
client secret,
a username,
and a password.

Note that while there is only one client ID and secret per organization, there may be multiple user accounts within the organization, each identified by a username and password.

Assuming this information is present in the environment variables CLIENT_ID, CLIENT_SECRET, USERNAME, and PASSWORD, then a token can be obtained by issuing the following shell command:

TOKEN=$(curl -s -d 'client_id=$CLIENT_ID' -d 'client_secret=$CLIENT_SECRET'  -d 'username=$USERNAME' -d 'password=$PASSWORD' -d 'grant_type=password' 'https://auth.gke.vathos.net/auth/realms/picking/protocol/openid-connect/token' | jq '.access_token' | sed 's/"//g' )

The token will be saved to the environment variable TOKEN. Note that the SSO server will reply with a JSON-encoded string, containing the token among other things, which is parsed by piping the server response into jq and sed.

In Python, the authentication request looks like:

def get_user_token(client_id, client_secret, user, password):
  r"""
  Gets a bearer token for a given user token."
  """
  token_response = requests.post(
      'https://auth.gke.vathos.net/auth/realms/picking/protocol/openid-connect/token',
      headers={'content-type': 'application/x-www-form-urlencoded'},
      data={
          'client_id': client_id,
          'client_secret': client_secret,
          'username': user,
          'password': password,
          'grant_type': 'password',
      })
  return token_response.json()['access_token']

Note that for the sake of simplicity, no exception-handling is implemented in this code snippet.

Service account tokens

A service account is an account not associated with a person but rather a device or organization. It can be obtained with the client ID and secret alone specifying the grant type 'client_credentials':

def get_service_account_token(client_id, client_secret):
  r"""
  Gets a bearer token for a given user token."
  """
  token_response = requests.post(
      'https://auth.gke.vathos.net/auth/realms/picking/protocol/openid-connect/token',
      headers={'content-type': 'application/x-www-form-urlencoded'},
      data={
          'client_id': client_id,
          'client_secret': client_secret,
          'grant_type': 'client_credentials'
      })
  return token_response.json()['access_token']