Skip to main content

Access and authentication

Accessing the API​

The API is available over HTTPS and is located at https://{client}-api.phlextmf.com/auth/v5/auth/login.

Authentication​

The API accepts payloads in JSON. You must use the Accepts header (application/json) to indicate this.

You must authenticate API calls using JSON Web Token (JWT), an open standard that defines a way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed, using either a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Once the user is logged in, each subsequent request includes the JWT, which grants access to routes, services, and resources.

To grant access to the PhlexTMF resources, you need to use the Auth POST endpoint to log into the system and fetch a JSON web token.

For more information, see Managing API requests and Auth.

Authentication request​

Follow the below steps for the authentication process:

Create a POST request:

https://{client}-api.phlextmf.com/auth/v5/auth/login

In headers make the following selections:

Host: client-api.phlextmf.com
Content-Type: application/json

Populate the body of your request with the relevant data:

{
"Username":"[email protected]",
"Password":"c113ntPa55w0Rd!"
}

If the credentials are correct, the API returns a 200 response code indicating the JSON web token has been successfully returned.

This process will lead to the generation of a token which must be used in all subsequent calls via the HTTP in the relevant header pertaining to authorisation.

Authorization: bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Parts of the token​

JSON Web Tokens consist of three parts separated by dots (.) in the format xxxxx.yyyyy.zzzzz:

  • Header
  • Payload
  • Signature

The header consists of the type of the token (always JWT), and the hashing algorithm being used, such as HMAC SHA256 or RSA.

For example:

{
    "alg": "HS256",
    "typ": "JWT"
}

This JSON is then Base64Url encoded.

Payload​

The payload contains the claims, which are statements about the user and additional data. The JWT specification defines seven claims that can be included in a token. These are registered claim names, and they are:

  • iss (issuer)
  • sub (subject)
  • aud (audience)
  • exp
  • nbf
  • iat
  • jti

You might then use public claim names, such as:

  • auth_time
  • acr
  • nonce

There are also private claim names, which you can use to convey identity-related information, such as name or department.

Because public and private claims are not registered, you must avoid name collisions.

For example:

{
    "sub": "1234567890",
    "name": "Isaac Newton",
    "admin": true
}

The payload is then Base64Url encoded.