JWT Tokens

Access Token

JWT Access token is used for authentication and authorization:

  • Authentication is performed by verifying JWT Access Token signature. If signature proves to be valid, access to requested API resource is granted.
  • Authorization is done by looking up privileges in the scope attribute of JWT Access token.

It must be set in Authorization header of each API call. First of all you'll have to get this JWT.

Refresh Token

Refresh token is long-lived token used to request new Access tokens. It's expiration time is greater than expiration time of Access token.

How to

We provide a POST endpoint to get and refresh JWT tokens. See JWT Authentication for more details. You can get a token by 2 different ways:

  • By using realm name, client secret and specifying grant type to client_credentials. If you are an application.
  • By using realm name, username, password and specifying grant type to password. If you are a user (human).

Grant type "client_credentials" sample request

{
  "clientSecret": "XXX-XXX-XXX-XXX",
  "realmName": "com2us",
  "grantType": "client_credentials"
}

Grant type "password" sample request

In this case "grantType" is not mandatory as the default value is "password".

{
  "username": "jdoe",
  "password": "987654321",
  "realmName": "com2us"
}

Sample response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJueVpwKdkzknfgdXpUb0dPUXhXckpYdVY4WGdYVUd3MzlUeHNUc1R0ZUlvIn0.eyJqdGkiOiI0NmJjYjg5NC0xYTJiLTQ3YjctYWQ4ZS0yOTk4ZGJiZjQ5Y2MiLCJleHAiOjE0OTMzMDg1MjEsIm5iZiI6MCwiaWF0IjoxNDkzMzA4NDYxLCJpc3MiOiJodHRwczovL2F1dGguc3RhZ2luZy5uZXh3YXkuYnVpbGQvYXV0aC9yZWFsbXMvbWFzdGVyIiwiYXVkIjoiYWRtaW4tY2xpIiwic3ViIjoiMDFkYmYwYTAtODVhMi00NDRhLWI1OWItZjAwODJiOGZmZmIzIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiYWRtaW4tY2xpIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMzcxYTdiM2ItNmEyNC00NzliLTg5ZWUtMDQ4ZTdkYTczNmI1IiwiYWNyIjoiMSIsImNsaWVudF9zZXNzaW9uIjoiNTFiOGM3YzMtZTM1NC00NmYyLWFiN2YtM2JmMjY0OGE1N2QyIiwiYWxsb3dlZC1vcmlnaW5zIjpbXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImNyZWF0ZS1yZWFsbSIsImFkbWluIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiY29tMnVzLXJlYWxtIjp7InJvbGVzIjpbInZpZXctaWRlbnRpdHktcHJvdmlkZXJzIiwidmlldy1yZWFsbSIsIm1hbmFnZS1pZGVudGl0eS1wcm92aWRlcnMiLCJpbXBlcnNvbmF0aW9uIiwiY3JlYXRlLWNsaWVudCIsIm1hbmFnZS11c2VycyIsInZpZXctYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1ldmVudHMiLCJtYW5hZ2UtcmVhbG0iLCJ2aWV3LWV2ZW50cyIsInZpZXctdXNlcnMiLCJ2aWV3LWNsaWVudHMiLCJtYW5hZ2UtYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1jbGllbnRzIl19LCJhdmFzdC1yZWFsbSI6eyJyb2xlcyI6WyJ2aWV3LWlkZW50aXR5LXByb3ZpZGVycyIsInZpZXctcmVhbG0iLCJtYW5hZ2UtaWRlbnRpdHktcHJvdmlkZXJzIiwiaW1wZXJzb25hdGlvbiIsImNyZWF0ZS1jbGllbnQiLCJtYW5hZ2UtdXNlcnMiLCJ2aWV3LWF1dGhvcml6YXRpb24iLCJtYW5hZ2UtZXZlbnRzIiwibWFuYWdlLXJlYWxtIiwidmlldy1ldmVudHMiLCJ2aWV3LXVzZXJzIiwidmlldy1jbGllbnRzIiwibWFuYWdlLWF1dGhvcml6YXRpb24iLCJtYW5hZ2UtY2xpZW50cyJdfSwibWFzdGVyLXJlYWxtIjp7InJvbGVzIjpbInZpZXctaWRlbnRpdHktcHJvdmlkZXJzIiwidmlldy1yZWFsbSIsIm1hbmFnZS1pZGVudGl0eS1wcm92aWRlcnMiLCJpbXBlcnNvbmF0aW9uIiwiY3JlYXRlLWNsaWVudCIsIm1hbmFnZS11c2VycyIsInZpZXctYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1ldmVudHMiLCJtYW5hZ2UtcmVhbG0iLCJ2aWV3LWV2ZW50cyIsInZpZXctdXNlcnMiLCJ2aWV3LWNsaWVudHMiLCJtYW5hZ2UtYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1jbGllbnRzIl19fSwibmFtZSI6IiIsInByZWZlcnJlZF91c2VybmFtZSI6ImtleWNsb2FrIn0.X7JqAS_aireUSJOObExUhbtLM1KKUCMISjJqXelwYpmIZp_1osamYYsiJbC0hMIFhcU0ttLv9Bk-68Jo6Us1ZFJOqVnWieB1Lw6fS_HXjEa57RVkgM4wsC9I8AW1ZOGmfahfKLRgmy1YNXZVPXCjUJf1TCDGacJZKPnckNSJJD0vsSffVz7LCnQRMH6mdx-bL__QkLN8l-09YQIPVjAyVSV_0qtELRKSVBJkDeI7Pi2TSJOuDhF1nUErQCKO_3Cp74tr6Gf38N3d6hHxUYDOCxYQ5lQoDFR21FAYjtP-AvDLoTJmwf5VkITgfN-vmWv7uyztnZA_thoHniSmkZxtTA",
  "expires_in": 60,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJueVpwY3NfsdqsdFZEb0dPUXhXckpYdVY4WGdYVUd3MzlUeHNUc1R0ZUlvIn0.eyJqdGkiOiIzZTg3YjhhYi03MDVjLTQxZWEtODFiMS1iZjNiNGEyOWU2MWUiLCJleHAiOjE0OTMzMTAyNjEsIm5iZiI6MCwiaWF0IjoxNDkzMzA4NDYxLCJpc3MiOiJodHRwczovL2F1dGguc3RhZ2luZy5uZXh3YXkuYnVpbGQvYXV0aC9yZWFsbXMvbWFzdGVyIiwiYXVkIjoiYWRtaW4tY2xpIiwic3ViIjoiMDFkYmYwYTAtODVhMi00NDRhLWI1OWItZjAwODJiOGZmZmIzIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImFkbWluLWNsaSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjM3MWE3YjNiLTZhMjQtNDc5Yi04OWVlLTA0OGU3ZGE3MzZiNSIsImNsaWVudF9zZXNzaW9uIjoiNTFiOGM3YzMtZTM1NC00NmYyLWFiN2YtM2JmMjY0OGE1N2QyIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImNyZWF0ZS1yZWFsbSIsImFkbWluIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiY29tMnVzLXJlYWxtIjp7InJvbGVzIjpbInZpZXctaWRlbnRpdHktcHJvdmlkZXJzIiwidmlldy1yZWFsbSIsIm1hbmFnZS1pZGVudGl0eS1wcm92aWRlcnMiLCJpbXBlcnNvbmF0aW9uIiwiY3JlYXRlLWNsaWVudCIsIm1hbmFnZS11c2VycyIsInZpZXctYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1ldmVudHMiLCJtYW5hZ2UtcmVhbG0iLCJ2aWV3LWV2ZW50cyIsInZpZXctdXNlcnMiLCJ2aWV3LWNsaWVudHMiLCJtYW5hZ2UtYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1jbGllbnRzIl19LCJhdmFzdC1yZWFsbSI6eyJyb2xlcyI6WyJ2aWV3LWlkZW50aXR5LXByb3ZpZGVycyIsInZpZXctcmVhbG0iLCJtYW5hZ2UtaWRlbnRpdHktcHJvdmlkZXJzIiwiaW1wZXJzb25hdGlvbiIsImNyZWF0ZS1jbGllbnQiLCJtYW5hZ2UtdXNlcnMiLCJ2aWV3LWF1dGhvcml6YXRpb24iLCJtYW5hZ2UtZXZlbnRzIiwibWFuYWdlLXJlYWxtIiwidmlldy1ldmVudHMiLCJ2aWV3LXVzZXJzIiwidmlldy1jbGllbnRzIiwibWFuYWdlLWF1dGhvcml6YXRpb24iLCJtYW5hZ2UtY2xpZW50cyJdfSwibWFzdGVyLXJlYWxtIjp7InJvbGVzIjpbInZpZXctaWRlbnRpdHktcHJvdmlkZXJzIiwidmlldy1yZWFsbSIsIm1hbmFnZS1pZGVudGl0eS1wcm92aWRlcnMiLCJpbXBlcnNvbmF0aW9uIiwiY3JlYXRlLWNsaWVudCIsIm1hbmFnZS11c2VycyIsInZpZXctYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1ldmVudHMiLCJtYW5hZ2UtcmVhbG0iLCJ2aWV3LWV2ZW50cyIsInZpZXctdXNlcnMiLCJ2aWV3LWNsaWVudHMiLCJtYW5hZ2UtYXV0aG9yaXphdGlvbiIsIm1hbmFnZS1jbGllbnRzIl19fX0.JuCjOQCd7WAYT0t1Q9OVTCRxG3AbAYgSDbFK1xwFihPYBz5PKnMQNt1CXFKJ35HceRZ7_BFV0NoCcSypTbwA9xW617-MEX7q3IekCGhjBijYx0JJx1grg6Ohqi3op7yMVXr0rZZgwMy50pqD0OJbyhuDagc-boLdys2AwEB0jEg_3Mr-2XNM7FQtrqMgmplyApgkryF5AHpdZNQ200-L7BPGjFdaEVZOZFLaG8Qjkxyi7Izv-2kFXgy8bnDTzFs5HjP4cfQNJm78-oDR6-mOcQBLEbq6PK7cNbTr7H5EyEcchsK1tATw626_QAwUeqAlaHBvUoW4q2vlluyr5-pD0A",
  "token_type": "bearer",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJueVpwY3NCa3hieXpUFGFEGHHgckpYdVY4WGdYVUd3MzlUeHNUc1R0ZUlvIn0.eyJqdGkiOiIyYjQ4OGUyNC1iZGVhLTRkYWYtOGE3Yi1lMmM0NDQwMThmYjgiLCJleHAiOjE0OTMzMDg1MjEsIm5iZiI6MCwiaWF0IjoxNDkzMzA4NDYxLCJpc3MiOiJodHRwczovL2F1dGguc3RhZ2luZy5uZXh3YXkuYnVpbGQvYXV0aC9yZWFsbXMvbWFzdGVyIiwiYXVkIjoiYWRtaW4tY2xpIiwic3ViIjoiMDFkYmYwYTAtODVhMi00NDRhLWI1OWItZjAwODJiOGZmZmIzIiwidHlwIjoiSUQiLCJhenAiOiJhZG1pbi1jbGkiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiIzNzFhN2IzYi02YTI0LTQ3OWItODllZS0wNDhlN2RhNzM2YjUiLCJhY3IiOiIxIiwibmFtZSI6IiIsInByZWZlcnJlZF91c2VybmFtZSI6ImtleWNsb2FrIn0.Y1ThHIRibQu-lK-JIbRB2KKDf6mC42fG5DwCy_QTYR_Yv7_sCDegin_dtcVr7VRBaIsDx6wK21NLZIp4ioJm6LDRi_lpLISH1uqrbAugoNpgShPoN8AetKruHBguJJQ8YKjojk7c3v2RB32OPJq_-ZXOKJtEwUFGTyafM6950p0QNCDHCldLnzAuALh0oTIwm5wfqpOru9B1BHImnaQ-lUFlhEnJTngzv3mIKfe1ln7WiWENsHSpxhcm4OY2ukXI5iLDetFFGJeWaqpGyFDpi9eOZpRmKWcfcVOYDTr4bjObG5Ud5ReteKD20FUtBSZncZCJqUko-np8FDXrHiFGsQ",
  "not-before-policy": 0,
  "session_state": "371a7b3b-6a24-479b-89ee-048e7da736b5"
}

Afterwards you should use a refresh token instead of client secret each time to refresh your access token. This way you are extending your session instead of creating a new one. As refresh token also has expiration time, when it expires, you need to get a new one using client secret in the request.

Sample refresh request

{
  "clientSecret": "XXX-XXX-XXX-XXX",
  "realmName": "com2us",
  "grantType": "refresh_token",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJDbDFIczhVSnRsYUhDbVlZOWs1amVSZzVZRGlIN1lkbTZlNXU4blJydWc0In0.eyJqdGkiOiJkNWQzYjUwYi1iNmZiLTRhNzAtYjg1Ni1mOTIzYjkwYTUxMjAiLCJleHAiOjE0OTQ0ODk5NDYsIm5iZiI6MCwiaWF0IjoxNDk0NDg4MTQ2LCJpc3MiOiJodHRwczovL2F1dGguc3RhZ2luZy5uZXh3YXkuYnVpbGQvYXV0aC9yZWFsbXMvZGlnaXRhbGNvbnRlbnRzdGFnaW5nIiwiYXVkIjoiYXBpLXNlcnZpY2VzIiwic3ViIjoiOGM0MWQyMTQtOTY4Ni00YjNkLWJjZGUtODQwMzU4NDQ0NDQ1IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImFwaS1zZXJ2aWNlcyIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjZlMTFlZGRhLWJiZDItNDM1Yy04ZDZiLTgxOGFhMmIyZDc1ZSIsImNsaWVudF9zZXNzaW9uIjoiYjE4Mzc1OTUtY2VlOS00YjNmLWFjZWEtZjQzMzMwMWZkYTYxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfSwiZGlnaXRhbGNvbnRlbnQtcHJveHktc2VydmljZSI6eyJyb2xlcyI6WyJwb3N0IiwiZ2V0IiwicHV0Il19fX0.SF7JDl0vqeG1QqnXPnGKPyMI9mX_8g5zRI2P9tg4SVr1TYBG7Jp88VPy9d5hNwnutmkSqPeuZTfHxEh5gFOBKYixpGJQC6A3SKJsxP-GnpjV026PWvoweFxaJTf8Y4IwR1crJMeEtI4YlAW6A9_hFr0a03DgyIeOtOtB7R7xs1teU00rj1m9gCRem9VzJBvTqvEG2WqlTIM7YNZZg7Wr8LxQpuZA1eZ5ns9hJWF5s-BUsmEjzl8yuyn2-88-cae59I8ev6qUPGnNqG0zZpTuWR2hFJdPveiKPamV0ScL1laJRkXxG9AfXBULjIeHf8DZpK49uuD9jQDJPXMGioeEKg"
}