Authorization process

Less than 5 minutes to read

Pairing request

The 3rd party application calls the pairing authorization API to start the permission granting process, this is an asynchronous API since it requires the X3 Customer Configuration validation to access Customer data.

Requirements for this step:
- Root API for your region, e.g: https://api.myregion-sagex3.com/v1/
- A registered application (please follow the Quick Start Guide to know how to register an application) with the following:
  - client ID, e.g: clientID
  - client redirect URI, e.g: https://3rd.app.com/callback
  - X3 customer URL, e.g: https://x3.customer.com
- A X3 User with the correct security profile to accept the pairing request (Go to Administration > Users > Security profiles, and on the ‘thirdParties’ line ensure that, at least ,‘Create’, ‘Read’ and ‘Write’ are checked.):
API call example:
```
      HTTPS 1.1 GET https://api.myregion-sagex3.com/v1/token/authorise
      client_id= clientID
      scope = api.dataIngestion customer=https://x3.customer.com
      redirect_uri = https://3rd.app.com/callback
      state= 1234
```
Please note: the state parameter is generated by the 3rd party application to mitigate Cross-Site Request Forgery attacks. “When you use state for CSRF mitigation on the redirection endpoint, that means that within the state value there is a unique and non-guessable value associated with each authentication request about to be initiated. It’s that unique and non-guessable value that allows you to prevent the attack by confirming if the value coming from the response matches the one you expect (the one you generated when initiating the request). The state parameter is a string so you can encode any other information in it.” (from Auth0 docs).

If the Customer configuration is not found, it’s developer’s responsibility to read from the callback the error returned to inform the customer about the cause of the error, a typical callback “not found” looks like:
```
      HTTP 307 POST https://3rd.app.com/callback
      statusCode=404
      error=Could not associate the requested url with an active X3 Cloud customer
```
For other possible errors, click here.

Redirection to the X3 Customer configuration

If the Customer configuration is found, the API returns a URL to redirect to that ending application approval page.
```
      HTTP 307 GET https://x3.customer.com/appAccess?id=dfsdfejjer123k
```

Customer approval

The browser brings the Customer to the pending application approval with scope page. The Customer can then accept or reject the access request. If the request is accepted, the Application is then notified of the Customer validation by callback:
```
      HTTPS 1.1 POST https://3rd.app.com/callback
      authorizationCode=<accesscode>
      state=1234
      endpoint=https://api.customerregion-sagex3.com/v1
```

Please note: the state parameter is returned in the callback. So, it’s developer’s responsibility to read from the url redirected to developer’s application and extract the state, make sure the state matches (to prevent CSRF attacks). The Application has 1 minute to ask for its access tokens with a code given by the Customer.

When the regional api endpoint you are using is not associated to the customer configuration, a parameter called endpoint will be present in the callback. The 3rd party application has to use this endpoint for further calls instead of its known regional root API endpoint.

Exchange the authorization code for tokens

API call example: When the third party application is called back with Access Code, it can call Token API to exchange this code to tokens:
```
      HTTPS 1.1 POST https://api.customerregion-sagex3.com/v1/token
      //body content in JSON format
      {
          "code"="accesscode",
          "client_id" : "clientID",
          "client_secret": "clientSecret",
          "grant_type":  "authorization_code",
          "redirect_uri" : "https://3rd.app.com/callback"
      }
```
```
      {
          "access_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.TTTTTTTTTTTTTTTTTTTTTT",
          "scope":"api.dataIngestion",
          "token_type":"bearer",
          "expires_in":300,
          "refresh_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.RRRRRRRRRRRRRRRRRRRRRR",
          "refresh_token_expires_in":2678400
      }
```
There are 2 tokens returned:
- One access token usable for 5 minutes on Customer APIs.
- One refresh token usable for 30 days to get a new access and refresh token
The Application has 30 days to ask for a new access and refresh token using its current refresh token. It gets a new access and refresh token and can repeat the access mechanism without the Customer contribution.

After 30 days without usage of the refresh token, the Application needs to re-perfom the first step with Customer approval to be able to get access again to the Customer data.

Finally, the Customer can disable the application access from its X3 configuration at any time.

Please note that the token information is a piece of confidential information between X3 and your application. It must not be divulged to any third party as this does compromise the confidentiality and integrity of customer data. The third party application has the responsibility to store these tokens in a secure and encrypted way. For each customer, the application should keep the following formation:
- The customer url as it will be used as a way to identify a customer when a notification is sent to the third party application in the future.
- The regional api url to use for this customer
- The access token (encrypted, can be stored in a session since the lifetime is rather short)
- The refresh token (encrypted)
More information about tokens and their operations, click here.