2FA Login for API Access

Apiax offers 2FA login with self singed JWT if you require a higher degree of security.

Find in the table below, all the details.


Endpoint https://auth.apiax.io/auth/realms/apiax/protocol/openid-connect/token This endpoint creates tokens.
Method POST


Header Content-Type: application/x-www-form-urlencoded


Form values

       grant_type: password
       client_assertion_type:	urn:ietf:params:oauth:client-assertion-type:jwt-bearer
       username: _YOUR_USER_NAME_
       password: _YOUR_USER_PASSWORD_
       client_assertion: _CLIENT_ASSERTION_

Form parameter


          "access_token": "ACCESS_TOKEN",
          "expires_at": JAVA_TIMESTAMP,
          "refresh_expires_in": 0,
          "refresh_token": "REFRESH_TOKEN",
          "token_type": "bearer",
          "not-before-policy": JAVA_TIMESTAMP,
          "session_state": "UUID",
          "scope": "TOKEN_VALIDITY_SCOPES"


The response contains the access token at the JSON path $.access_token. For security reasons never share the access token or the refresh token found at the JSON path $.refresh_token.

You can use the access token as a bearer authentication header for subsequent API calls.

Authentication:Bearer ACCESS_TOKEN


The client requires an RS256 key pair. The private key is only visible to the client, which uses it to sign the client_assertion token.

Notice: The client must share the public key with Apiax for validity verification of the client_assertion token.


The 2FA flow is the following:

  1. The client creates the self-signed client_assertion token, which is the 2nd factor of the authentication.

  2. The client requests the generation of an access_token using username, password and the client_assertion token. The client gets a new access_token valid for 30 minutes if the verification is successful.

  3. The client uses the access_token while it is valid to access the resources/services for rule evaluation and taxonomy querying.


Client Assertion

The client assertion is a self-signed JWT with the following content:


      {"alg":"RS256", "typ":"JWT"}
        "sub": SUBJECT,
        "aud": "https://auth.apiax.io/auth/realms/apiax/protocol/openid-connect/token",
        "iss": ISSUER,
        "exp": EXPIRATION_TIME,
        "iat": ISSUED_AT,
        "jti": JWT_ID


Variable Description Example
SUBJECT The subject is to whom the token refers to. The Apiax support gives you this value. "MyCompany"
ISSUER The issuer is who created and signed this token. The Apiax support gives you this value. "MyCompany"
EXPIRATION_TIME The expiration time is the time in seconds since the Unix epoch. You choose how long the token should be valid. 1604689530
ISSUED_AT Issued at - the time in seconds since the Unix epoch. It is the time of the token creation. 1604686530
JWT_ID JWT ID - is the unique identifier for this token. This ID must be unique for every time you use a token. Apiax suggests using new UUIDs for every request. // SUBJECT + "-" + UUID()


Client assertion example

Find below an example of a complete client assertion.


header = {
  "alg": "RS256",
  "typ": "JWT"

payload = {
  "sub": "MyCompany",
  "aud": "https://auth.apiax.io/auth/realms/apiax/protocol/openid-connect/token",
  "iss": "MyCompany",
  "exp": 1604689530, // <- seconds since 1970-01-01!
  "iat": 1604686530, // <- seconds since 1970-01-01!
  "jti": "MyCompany-9cffb95a-2385-11eb-adc1-0242ac120002" 

claims = base64UrlEncode(header) + "." + base64UrlEncode(payload)
client_assertion = claims + "." + RSASHA256(claims, private_key_pem)

// if done right the token will have the form BASE64-ENCODE-HEADER '.' BASE-ENCODED-PAYLOAD '.' SIGNATURE


Creating Access Token

Using the client_assertion token created in step 1, you can now retrieve an access token.


curl --request POST \
  --url https://auth.apiax.io/auth/realms/apiax/protocol/openid-connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=password' \
  --data 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data 'username=MY_USER_NAME' \
  --data 'password=MY_USER_PASSWORD' \
  --data 'client_assertion=MY_CLIENT_ASSERTION_TOKEN'


You can retrieve the access token from the response at the JSON path $.access_token.


Was this article helpful?



Article is closed for comments.

Still have questions?

Please submit a request and we will get back to you shortly.

Submit a ticket