Authentication

You will need:

Authentication across all APIs is based on OAUTH2

Therefore the authentication process is always in two stages:

  1. Call the authorisation server. Assuming secure machine-to-machine services, call it with client ID and client secret via POST. Note that this may raise security issues when the services are not secure.
  2. The authorisation server checks the credentials and returns an access token. Developers can use the access token for subsequent API calls until it expires.

There are two main flows when it comes to authentication and this difference is based on the kind of credentials you have access to. These types are client-credential based authentication and password-based authentication.

Authentication flow diagram
fig:1.0 illustration of OAUTH2 flow.

Client Credential Based Authentication

Sample request

As mentioned above we need an access token to access all other endpoints.

Below is a sample request in CURL.


      
curl --location --request POST 'https://login.etrusted.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=https://api.etrusted.com'


    
  • The header grant_type=client_credentials specifies that you will be authenticating using your client_id and client_secret
  • {client_id}: replace this with your client secret.
  • {client_secret}: replace this with your client credentials.

Sample response

The response of the authorization call contains an access token.


      {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJTVHpnYzZfTEM3ZHVnZkNoZVpoUzQyd0dNWVAyM0lBTUdkWGUtWTJrb3ZjIn0.eyJleHAiOjE2MzY0NTA0NzksImlhdCI6MTYzNjQ1MDE3OSwianRpIjoiNmNiODVlMTQtZmZlMC00MzdlLTkyMmMtMjRjMDZmM2ViMjNjIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi1xYS5ldHJ1c3RlZC5jb20vYXV0aC9yZWFsbXMvYnVzaW5lc3MtUUEiLCJhdWQiOlsiYjJiLWN1c3RvbS1jbGllbnQiLCJhY2NvdW50Il0sInN1YiI6IjY3MjIxYWRiLWZhYTMtNDdiMy1hMmQ4LWM2NThkZDk5NDNkYiIsInR5cCI6IkJlYXJlciIsImF6cCI6IkpuRGFFV042NG4wbThtSlZqSGdTUG11emJHWDNua2Z0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwczovL2FwaS5ldHJ1c3RlZC5jb20iXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImIyYl91c2VyIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiSm5EYUVXTjY0bjBtOG1KVmpIZ1NQbXV6YkdYM25rZnQiOnsicm9sZXMiOlsidW1hX3Byb3RlY3Rpb24iXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImFyZWFzLWFsbG93ZWQiOlsibWFycyJdLCJjbGllbnRIb3N0IjoiMTg1LjYuMjMzLjE2MyIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SWQiOiJKbkRhRVdONjRuMG04bUpWakhnU1BtdXpiR1gzbmtmdCIsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1qbmRhZXduNjRuMG04bWp2amhnc3BtdXpiZ3gzbmtmdCIsImh0dHBzOi8vZXRydXN0ZWQuY29tIjp7ImFjY291bnRSZWYiOiJhY2MtMWQyZTZkZWYtOTBiZi00NzY3LTg1YTEtZjg3MjM2YTc5NzA0Iiwicm9sZSI6Im93bmVyIiwicGVybWlzc2lvbnMiOnsidXJuIjoidXJuOmV0cnVzdGVkOioifX0sImlkZW50aXR5UmVmIjoiaWRuLThjYmYwYWUyLWZlODUtNDRmNC1hNTRlLTU3ODE1YzFiMWZjNSIsImNsaWVudEFkZHJlc3MiOiIxODUuNi4yMzMuMTYzIiwiZW1haWwiOiJzZXJ2aWNlLWFjY291bnQtam5kYWV3bjY0bjBtOG1qdmpoZ3NwbXV6Ymd4M25rZnRAcGxhY2Vob2xkZXIub3JnIn0.IA7Lwkw3Xn94cRCKbhETxPOZmSyHtNdLqjbriEsERDQOzTkMAibaAUCkL1emEytHplhaGv_T97JHU_hxSjTM_WexLvJcD_rDbjkcOJgqv4-48r2KqxpO_qzcNms1pnsVsj0ZGhlkVKiyD6VeeOfv04nTiZcXOwLgPa_BKrKwooem6UBC8Pkc9Rl41I0zZHCevOr_ihm7Z1gEE32_tkd4CuwNXEf-EhvM6F4-KWIQX5kYYPQciZ6CdGWYcdHfplSbh5eLI-dt-XTUBKoxNsGO52Aa3kjiGJ3YaIC_UVcKhF9QfDINMSbGYclNHovmc5b22R6AWmGMZDhd-c6glmh8lQ",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "bearer",
    "not-before-policy": 1635873642,
    "scope": "profile email"
}

    

When you authenticate using your API credentials you get back an access token that expires in 300 seconds which is 5 minutes from the time it was last used. This means it will only expire if you don't use it continuously. With that being said you can always request a new token by re-authenticating.

Password Based Authentication

If you have a username and password credentials then you will have to autheticate using the password based authentication approach. This is similar to the client-credential authentication with a few differences.

Sample request


      curl --location --request POST 'https://login.etrusted.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=mars-control-centre-client' \
--data-urlencode 'username={username_goes_here}' \
--data-urlencode 'password={password_goes_here}'

    
  • The header grant_type=password specifies that the authentication is password based.
  • client_id=mars-control-centre-client: This helps identify the type of username/password combo you have. In this case this is your control center login.
  • {username_goes_here}: replace this with your username.
  • {password_goes_here}: replace this with your password.

Sample response


      {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImFueS1raWQtbnVtYmVyIn0.eyJqdGkiOiIuLi4iLCJleHAiOjE1NTc4Mzk2NDIsIm5iZiI6MCwiaWF0IjoxNTU3NzUzMjQyLCJpc3MiOiJodHRwczovL2xvZ2luLmV0cnVzdGVkLmNvbS9hdXRoL3JlYWxtcy9idXNpbmVzcyIsImF1ZCI6Imtub3duLWF1ZCIsInN1YiI6InN1Yi11dWlkIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoia25vd24tYXVkIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoic3RhdGUtdXVpZCIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibXkiLCJvcmlnaW5zIl0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm15Iiwicm9sZXMiXX19LCJuYW1lIjoiRmlyc3ROYW1lIExhc3ROYW1lIiwicHJlZmVycmVkX3VzZXJuYW1lIjoibXlAZXhhbXBsZS5jb20iLCJodHRwczovL2V0cnVzdGVkLmNvbSI6eyJhY2NvdW50UmVmIjoiYWNjLVVVSUQiLCJyb2xlIjoib3duZXIiLCJwZXJtaXNzaW9ucyI6eyJyZXNvdXJjZVNldElkIjoidXJuOmV0cnVzdGVkOm15LXJvbGUxIn19LCJnaXZlbl9uYW1lIjoiRmlyc3ROYW1lIiwibG9jYWxlIjoiZW4iLCJmYW1pbHlfbmFtZSI6Ikxhc3ROYW1lIiwiZW1haWwiOiJteUBleGFtcGxlLmNvbSJ9.aUENy65fluD21xNf-yfWadkEx8zSWADZA7JxdYURE4w",
    "expires_in": 300,
    "token_type": "Bearer",
    "refresh_token":  "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImFueS1raWQtbnVtYmVyIn0.eyJqdGkiOiIuLi4iLCJleHAiOjE1NjU1MjkyNDIsIm5iZiI6MCwiaWF0IjoxNTU3NzUzMjQyLCJpc3MiOiJodHRwczovL2xvZ2luLmV0cnVzdGVkLmNvbS9hdXRoL3JlYWxtcy9idXNpbmVzcyIsImF1ZCI6Imtub3duLWF1ZCIsInN1YiI6InN1Yi11dWlkIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6Imtub3duLWF1ZCIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6InN0YXRlLXV1aWQiLCJyZXNvdXJjZV9hY2Nlc3MiOnsicmVhbG0tbWFuYWdlbWVudCI6eyJyb2xlcyI6WyJteSIsInJvbGVzIl19fX0.XhlX-LKerNl0paTtHPfNmnMkHYbHbxbUeWR0IHYnOuc",
    "refresh_expires_in": 7200
}

    

You get back an access_token that you can now use to access other APIs, this access_token has an expiry time of 300 seconds or 5 minutes.

To request a new access_token when it's expired you can use the refresh_token which although expires, has a longer duration of 7200 seconds which is about 2 hours. This helps to prevent the use of your username and password in multiple places.

Fetching a new access token with the refresh token

Requesting a new access_token token using the refresh token is similar to the previous examples shown above, again with a few differences.

Sample request


      curl --location --request POST 'https://login.etrusted.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=mars-control-centre-client' \
--data-urlencode 'refresh_token={refresh_token_goes_here}'

    
  • The header grant_type=refresh_token specifies that the authentication is based on the refresh_token.
  • {refresh_token_goes_here}: Should be replaced with the refresh_token from your previous request.
  • Also remember to set the header client_id=mars-control-centre-client, this specifies which credential was used to issue the refresh_token.

Sample response


      {
   "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJpd0hzYW1feTRYUUlBVzQ1bHEtR2xMWWRPN1BfNUp2ZVdSeC0tM1kyeFlVIn0.eyJqdGkiOiIxMGY2NTRlNC1mMWQxLTRjYTAtYjljZC03NjRmNjBlNjIzYTgiLCJleHAiOjE2MzY0NTM2MTIsIm5iZiI6MCwiaWF0IjoxNjM2NDUzMzEyLCJpc3MiOiJodHRwczovL2xvZ2luLmV0cnVzdGVkLmNvbS9hdXRoL3JlYWxtcy9idXNpbmVzcyIsImF1ZCI6Im1hcnMtY29udHJvbC1jZW50cmUtY2xpZW50Iiwic3ViIjoiYTU1Y2ZlYTEtNGZmNS00Y2ViLWJhMjQtODI2MWFkNWQyYjAwIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoibWFycy1jb250cm9sLWNlbnRyZS1jbGllbnQiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiYWU4MjI1OC1mZWJiLTRhMTctOGFjMC02ZWU5YzkwYTFjMDMiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbImh0dHBzOi8vYXBwLmV0cnVzdGVkLmNvbSIsImh0dHBzOi8vYWRtaW4uZXRydXN0ZWQuY29tIl0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImFyZWFzLWFsbG93ZWQiOlsibWFycyIsIm15dHMiXSwiZW1haWxfdmVyaWZpZWQiOnRydWUsInNob3BMb2dpblV1aWQiOiJjYjU5NzkzNzJiYTcyM2RkNjVmZjJmZGY0MGFlMDZhZiIsImlzU2hvcEFkbWluIjpmYWxzZSwibmFtZSI6IkVucmljbyBUYWdlYm91IiwicHJlZmVycmVkX3VzZXJuYW1lIjoiY3N0ZXN0b3JkZXIrZXRydXN0ZWRlbnJpY29AZ21haWwuY29tIiwiaHR0cHM6Ly9ldHJ1c3RlZC5jb20iOnsiYWNjb3VudFJlZiI6ImFjYy01YjU3MjQ5ZC05YjUxLTQ5ZWYtYWE4Yy0wMmI4ZGJhZDY3MjIiLCJyb2xlIjoib3duZXIiLCJwZXJtaXNzaW9ucyI6eyJ1cm4iOiJ1cm46ZXRydXN0ZWQ6KiJ9fSwibG9jYWxlIjoiZGUiLCJnaXZlbl9uYW1lIjoiRW5yaWNvIiwiaWRlbnRpdHlSZWYiOiJpZG4tY2I1OTc5MzctMmJhNy0yM2RkLTY1ZmYtMmZkZjQwYWUwNmFmIiwiZmFtaWx5X25hbWUiOiJUYWdlYm91IiwiZW1haWwiOiJjc3Rlc3RvcmRlcitldHJ1c3RlZGVucmljb0BnbWFpbC5jb20ifQ.H17AEwt--IDC9GUtH7YWveoCGCEmMPcsbt-LaR-79LyB8KTbNl2QKe6W9__DvOLfgDTcJ33Zx8z32n-5Xx-xCotwvY_7FOuxlaEZP42zOSPICCgWUXCZXb1g0jSg1NXFpXQ9nyXxMSKtli3AU8ToqJnB7tB8nOPoOcfnjjXwYUk9_mkJ8ApYJGp_lGo0K57gFVsM3sLxX9mjeWbmmZuSIX47yqFr30uMhZbtLTAdvdabLem39YjL_MtgaSLWyWhWCvPxONP9IskRAZsktigv0Mfd1yt3tXRCNUxVEpqyyYC3N0bsyM00kHbDG1VzLdyfYw7TQJbX942PSqkOZa_Xnw",
   "expires_in":300,
   "refresh_expires_in":7200,
   "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1M2I4MmJkMS1jNTc4LTRmMDctYmI2MC04MzQyYWQ4NGIzMmQifQ.eyJqdGkiOiI0ODliMTUzNC1mZmM4LTRhMTItOWFmZS04MDQyZmNiZjllZTgiLCJleHAiOjE2MzY0NjA1MTIsIm5iZiI6MCwiaWF0IjoxNjM2NDUzMzEyLCJpc3MiOiJodHRwczovL2xvZ2luLmV0cnVzdGVkLmNvbS9hdXRoL3JlYWxtcy9idXNpbmVzcyIsImF1ZCI6Imh0dHBzOi8vbG9naW4uZXRydXN0ZWQuY29tL2F1dGgvcmVhbG1zL2J1c2luZXNzIiwic3ViIjoiYTU1Y2ZlYTEtNGZmNS00Y2ViLWJhMjQtODI2MWFkNWQyYjAwIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6Im1hcnMtY29udHJvbC1jZW50cmUtY2xpZW50IiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiYmFlODIyNTgtZmViYi00YTE3LThhYzAtNmVlOWM5MGExYzAzIiwic2NvcGUiOiJlbWFpbCBwcm9maWxlIn0.lZP78PZRz9yi7hBJexiYB5apgChIfAy50lUvfmcf8dY",
   "token_type":"bearer",
   "not-before-policy":1632229476,
   "session_state":"bae82258-febb-4a17-8ac0-6ee9c90a1c03",
   "scope":"email profile"
}

    

The response from is similar to that of the password-based authentication, which means you get a new refresh_token which can be used in the future.

Using your access token

With the access_token you now have the complete access to all endpoints within the granted access group. All through the rest of the documentation, you will find information regarding how to use this access_token.

The access_token is valid for a limited time specified in the response of the authentication call.

Need further support?

Visit the Help Centre for further information, or contact us. Are some words or terms unfamiliar? Then visit the glossary for clarification.