Skip to content
Developerhome
Product homepage
X3

Token Management

  Less than to read

  1. Informations encoded inside tokens.
  2. Renew access token.
  3. Delete refresh token.

Tokens obtained through our authorization process are JSON Web Token (JWT) signed tokens:

  • Access token usable for 5 minutes on Customer APIs (e.g upload/export, graphql, etc…)

  • Refresh token usable for 30 days to get a new access and refresh token

One pair of generated access/refresh tokens are associated to just one customer. Therefore, if an application has multiple customers, it will need one pair of access/refresh tokens per customer in order to access customer data through REST API.

If the refresh token is expired or deleted by the customer, the application has to start over the initial authorization process.

Informations encoded inside tokens

  • Access token

    {
    "iss": "api.customerregion-sagex3.com",
    "aud": "api.customerregion-sagex3.com",
    "iat": 1548440700,
    "exp": 1548441000,
    "region": "customerregion",
    "sub": "e22327e6-a6ba-419a-b589-abaf305d4548",
    "azp": "c0febabe-0f39-44bc-afe1-4619719804c9",
    "scopes": "api.dataIngestion"
}
    • iss: Issuer of the token, would always be API gateway DNS that created the token, and is regional.
    • aud: Same as issuer in our case
    • iat: Token issued time
    • exp: Token expiration time (usually 5 minutes after iat)
    • region: X3 Cloud region e.g eu-prod, us-prod (used to perform transparent redirection between endpoints)
    • sub: X3 Cloud config-id concerned by the token
    • azp: Id of the application for which the token was issued
    • scopes: Access scope granted for the token

  • Refresh token

    {
    "jti": "b45d1a36-1f0d-4f03-8af8-e00ec656163a",
    "iss": "api.customerregion-sagex3.com",
    "aud": "api.customerregion-sagex3.com",
    "iat": 1548440700,
    "exp": 1551070500,
    "region": "customerregion",
    "sub": "e22327e6-a6ba-419a-b589-abaf305d4548",
    "azp": "c0febabe-0f39-44bc-afe1-4619719804c9",
    "scopes": "api.dataIngestion"
}
    • jti: Refresh token ID
    • iss: Issuer of the token, would always be API gateway DNS that created the token, and is regional.
    • aud: Same as issuer in our case
    • iat: Token issued time
    • exp: Token expiration time (usually 5 minutes after iat)
    • region: X3 Cloud region e.g eu-prod, us-prod (used to perform transparent redirection between endpoints)
    • sub: X3 Cloud config-id concerned by the token
    • azp: Id of the application for which the token was issued
    • scopes: Access scope granted for the token, for now read or write only

Renew access token

Everytime the application renews the access token, a new refresh token is issued at the same time along with the new access token, so the application has to store the new refresh token in order to renew the access token next time.

  • Requirements for this step:

    • A registered application with the following:

      • Unexpired refresh token e.g: “eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.ZZZZZZZZZZZZZZZZZZZZZZZZZZZ”
      • Client ID, e.g: clientID
      • Client secret, e.g:clientSecret

  • API call example:

      HTTPS 1.1 POST https://api.customerregion-sagex3.com/v1/token/
  //body content in JSON format
  {
      "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.ZZZZZZZZZZZZZZZZZZZZZZZZZZZ",
      "client_id" : "clientID",
      "client_secret": "clientSecret",
      "grant_type":  "refresh_token"
  }

      {
      "access_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.TTTTTTTTTTTTTTTTTTTTTT",
      "scope":"api.dataIngestion",
      "token_type":"bearer",
      "expires_in":300,
      "refresh_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.RRRRRRRRRRRRRRRRRRRRRR",
      "refresh_token_expires_in":2678400
  }

    For possible errors, click here.

Delete refresh token

Please note that operation if succesfully executed (obtains an HTTP 204) will remove the 3rd party application from X3 Customer approved applications list.

  • Requirements for this step:

    • A registered application with the following:

      • Unexpired refresh token
      • Client ID, e.g: clientID
      • Client secret, e.g:clientSecret

  • API call example:

    HTTPS 1.1 DELETE https://api.customerregion-sagex3.com/v1/token/
refresh_token= "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.ZZZZZZZZZZZZZZZZZZZZZZZZZZZ"
client_id= clientID
client_secret= client secret

    HTTP 204