Authorization code flow
This authentication scheme is considered to be the most secure, since instead of directing the authentication request to the user, the application directs it to the Vantage authorization server instead. The authorization server then authenticates the user and returns the authorization code to the client.
In order to prevent the authorization code from being intercepted, this authentication scenario uses a security extension called PKCE (Proof Key for Code Exchange). This extension works as follows: each authorization request requires a cryptographic random number to be generated and stored in code_verifier, which is then used to obtain a cryptographically signed value stored in code_challenge. This new value is then sent to the authorization server in order to obtain an authorization code.
For more information about PKCE, visit this link.
- Getting the authorization code
- Getting the authorization token
- Getting the refresh token
- Token lifetimes
Getting the authorization code
To begin the authentication process, the application should redirect you to the following address:
- https://vantage-eu.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions%20global.wildcard&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963 - for users in Western Europe,
- https://vantage-us.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions%20global.wildcard&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963 - for users in North America,
- https://vantage-au.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions%20global.wildcard&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963 - for users in Australia
with the following parameters:
| Parameter | Description |
|---|---|
| client_id |
The application identifier. For information on how to create a Vantage API Client (client_id and client_secret), see the Managing Tenant Vantage API Clients article. |
| redirect_uri | The URL of your application or website that is used to redirect the browser once access permissions have been granted. |
| response_type=code | Specifies that the authorization code response type is used. |
| scope=openid permissions global.wildcard | Specifies the permission scope. |
| state | An arbitrary string value that will contain the authorization result in the response. |
| code_challenge | Digitally signed value of the code_verifier code (using the code_challenge_method method). |
| code_challenge_method | The digital signature method for the code_verifier code (S256). |
| productId=a8548c9b-cb90-4c66-8567-d7372bb9b963 | The Vantage identifier. |
The values for response_type, scope, productId should be exactly as specified above. These keys, except response_type, are subject to change. Please put them in your configuration files, so that you can easily change them without rebuilding your entire integration.
A parameter called redirect_uri that contains your resource's identifier is used in Oauth 2.0 in order to allow Vantage to send the authorization code to your resource and then exchange that code for the access token, which is required for authentication in all subsequent API calls. Using this authentication method requires providing the value of the redirect_uri parameter to ABBYY technical support in order to have it whitelisted by the administrators.
Sample request
Once access permissions requested using the scope parameter have been verified to be granted, the browser is redirected to a special web page set up by the Vantage server. This web page has a dialog window that is used to undergo authorization using your account. This page should be opened using a browser that has a visible address bar, which will let you verify the page URL and the state of the connection's SSL certificate.
If your email address is connected to several accounts in different tenants, you will be asked to select a tenant and enter your password after you have specified your email address. You can also pass your tenant identifier (thetokenId parameter) directly using one of the following resources:
- https://vantage-eu.abbyy.com/auth2/{tenantId}/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions%20global.wildcard&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963 or https://vantage-eu.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963&tenantId=tenantId - for users in Western Europe,
- https://vantage-us.abbyy.com/auth2/{tenantId}/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions%20global.wildcard&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963 or https://vantage-us.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963&tenantId=tenantId - for users in North America.
- https://vantage-au.abbyy.com/auth2/{tenantId}/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions%20global.wildcard&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963 or https://vantage-au.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=external_app_redirect_uri&response_type=code&scope=openid%20permissions&state=state&code_challenge=code_challenge&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963&tenantId=tenantId - for users in Australia.
You will be required to enter the password for your tenant account.
Once you have entered your credentials, authorization is completed server-side, the application is granted access to the Vantage API, and you receive the authorization code in the response to your request.
Please be aware that if a site or application uses this authentication type, Vantage users will provide access to the Vantage API on their behalf to the site or app that you are adding to the list of allowed redirect URL's. To provide access to the site or app, users will be asked to authenticate in Vantage using their login and password. Once a user is authenticated, the site or app will be granted the following permissions:
- managing data catalogs in the Vantage tenant on behalf of the user,
- accessing skills in the Vantage tenant on behalf of the user,
- creating and accessing Vantage transactions on behalf of the user.
The site or app will not be able to change user's password, change the list of users in a Vantage tenant, or edit skills. Only access to the Vantage API will be provided. The user will not be able to revoke access once it has been granted.
Getting the authorization token
Once you have obtained the authorization code, you have one minute to exchange it for the access token. To do so, use the following:
- A POST request.
- The https://vantage-eu.abbyy.com/auth2/connect/token resource (for users in Western Europe), https://vantage-us.abbyy.com/auth2/connect/token resource (for users in North America), and https://vantage-au.abbyy.com/auth2/connect/token resource (for users in Australia).The https://vantage-eu.abbyy.com/auth (for users in Western Europe), https://vantage-us.abbyy.com/auth (for users in North America), and https://vantage-au.abbyy.com/auth (for users in Australia) resources are deprecated.
- A Content-Type header with the application/x-www-form-urlencoded encoding.
- A request body with the following parameters:
| Parameter | Description |
|---|---|
| code_verifier | The code that you have generated. Needed to confirm the initiation of the authorization request. |
| client_id |
The application identifier. For information on how to create a Vantage API Client (client_id and client_secret), see the Managing Tenant Vantage API Clients article. |
| client_secret |
Secure application key. For information on how to create a Vantage API Client (client_id and client_secret), see the Managing Tenant Vantage API Clients article. |
| code | Your authorization code obtained from the server. |
| redirect_uri | The URL of your application or website that is used to redirect the browser once access permissions have been granted. |
| grant_type=authorization_code | Specifies that the authorization code grant type is used. |
| scope=openid permissions global.wildcard offline_access |
Specifies the permission scope. To get a refresh token, you need to add offline_access to the scope. For more information, see Getting the refresh token. |
Sample request:
For Windows
For Linux
The server's response to your request will contain the access token:
Response
For more information about Authorization Code Flow, visit this link.
For each flow, the access_token key contains the token, while the expires_in key specifies how soon the token will expire (in seconds). By default, access token lifetime is 24 hours (for more information, see Token lifetimes). Add the following authorization header to all your requests to the ABBYY Vantage service and replace token with the value you received:
-H "Authorization: Bearer token"
|
Note that you can obtain several tokens using the same account.
For more information about the authorization token, visit this link.
Getting the refresh token
If the Allow issuing refresh tokens to refresh access tokens option was enabled when configuring the Vantage API client (for more information, see Creating a Client using the Vantage API) and the request of getting the access token contained the scope=openid permissions global.wildcard offline_access parameter, you will also receive an additional refresh token in the response to your request. Once you have a refresh token, you can refresh the access token using the following:
- A POST request.
- The https://vantage-eu.abbyy.com/auth2/connect/token resource (for users in Western Europe), https://vantage-us.abbyy.com/auth2/connect/token resource (for users in North America), and https://vantage-au.abbyy.com/auth2/connect/token resource (for users in Australia).The https://vantage-eu.abbyy.com/auth (for users in Western Europe), https://vantage-us.abbyy.com/auth (for users in North America), and https://vantage-au.abbyy.com/auth (for users in Australia) resources are deprecated.
- A Content-Type header with the application/x-www-form-urlencoded encoding.
- A request body with the following parameters:
| Parameter | Description |
|---|---|
| client_id |
The application identifier. For information on how to create a Vantage API Client (client_id and client_secret), see the Managing Tenant Vantage API Clients article. |
| client_secret |
A secure application key. For information on how to create a Vantage API Client (client_id and client_secret), see the Managing Tenant Vantage API Clients article. |
| refresh_token | Your refresh token obtained from the server. |
| grant_type=refresh_token | Specifies that the refresh token grant type is used. |
Sample request:
For Windows
For Linux
The server's response to your request will contain the new access and refresh tokens.
Access and refresh tokens are configured to have the following lifetimes:
- Access token lifetime (period of time during which the issued access token is valid)—24 hours.
- Refresh token lifetime (period of time during which the issued refresh token is valid)—30 days. A refresh token is issued after the initial authentication along with the first access token. While the refresh token is active, it can be used to obtain new access tokens. The refresh token cannot be extended; you can only obtain a new one through reauthentication.
22.12.2023 12:36:42