Authorization Code Flow

Use the OAuth 2.0 Authorization Code flow with PKCE to authenticate users against ABBYY Vantage and obtain access tokens for the Vantage API.

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

To begin the authentication process, redirect the user to the authorize endpoint, passing 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. Consider keeping them in configuration.

Sample Request

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.

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 (the tokenId parameter) directly using one of the following resources:

or

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. Use a POST request to the token endpoint with application/x-www-form-urlencoded data.

Request body 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.
client_secret	Secure application key.
code	Your authorization code obtained from the server.
redirect_uri	The redirect URL used in the authorize step.
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, add offline_access to the scope.

Sample request:

For Windows:

For Linux:

The server’s response to your request will contain the access token:

{
  "id_token": "<redacted>",
  "access_token": "<redacted>",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "<redacted>",
  "scope": "openid permissions global.wildcard offline_access legacy.client"
}

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 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 and the request for 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. Once you have a refresh token, you can refresh the access token using a POST request to the token endpoint with the following parameters:

Parameter	Description
client_id	The application identifier.
client_secret	A secure application key.
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:

Token lifetimes

Access and refresh tokens are configured to have the following lifetimes:

• Access token lifetime: Defines the time period during which the issued access token allows user access to Vantage. The default lifetime of an access token is 24 hours.
• Refresh token lifetime: Defines the absolute time period starting from the issuance of the first access token during which the issued refresh token can be used to renew the access token. The default lifetime of an refresh token is 30 days.