Skip to main content
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:
ParameterDescription
client_idThe 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_uriThe URL of your application or website that is used to redirect the browser once access permissions have been granted.
response_type=codeSpecifies that the authorization code response type is used.
scope=openid permissions global.wildcardSpecifies the permission scope.
stateAn arbitrary string value that will contain the authorization result in the response.
code_challengeDigitally signed value of the code_verifier code (using the code_challenge_method method).
code_challenge_methodThe digital signature method for the code_verifier code (S256).
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963The 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 
https://vantage-us.abbyy.com/auth2/connect/authorize?client_id=client_id&redirect_uri=https%3A%2F%2Fvantage-us.abbyy.com%2Flogin-callback&response_type=code&scope=openid%20permissions%20global.wildcard&state=ef30939211cc4ecb9a7a349b855c6a10&code_challenge=tA6ayQ5VUjLX2tufAKaHh-9bTAQ4hQQY5VZAoB2kG9o&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963
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: 
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%20global.wildcard&state=state&code_challenge=code_challenge
&code_challenge_method=S256&productId=a8548c9b-cb90-4c66-8567-d7372bb9b963&tenantId=tenantId
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:
ParameterDescription
code_verifierThe code that you have generated. Needed to confirm the initiation of the authorization request.
client_idThe application identifier.
client_secretSecure application key.
codeYour authorization code obtained from the server.
redirect_uriThe redirect URL used in the authorize step.
grant_type=authorization_codeSpecifies that the authorization code grant type is used.
scope=openid permissions global.wildcard offline_accessSpecifies the permission scope. To get a refresh token, add offline_access to the scope.
Sample request (Windows): 
curl --location --request POST "https://vantage-eu.abbyy.com/auth2/connect/token" \
  --data-urlencode "code_verifier=code_verifier" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret" \
  --data-urlencode "code=authorization code" \
  --data-urlencode "redirect_uri=external app redirect uri" \
  --data-urlencode "grant_type=authorization_code"
Also available for other regions: 
# North America
curl --location --request POST "https://vantage-us.abbyy.com/auth2/connect/token" \
  --data-urlencode "code_verifier=code_verifier" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret" \
  --data-urlencode "code=authorization code" \
  --data-urlencode "redirect_uri=external app redirect uri" \
  --data-urlencode "grant_type=authorization_code"

# Australia
curl --location --request POST "https://vantage-au.abbyy.com/auth2/connect/token" \
  --data-urlencode "code_verifier=code_verifier" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret" \
  --data-urlencode "code=authorization code" \
  --data-urlencode "redirect_uri=external app redirect uri" \
  --data-urlencode "grant_type=authorization_code"
Sample request (Linux): 
curl --location --request POST 'https://vantage-eu.abbyy.com/auth2/connect/token' \
  --data-urlencode 'code_verifier=code_verifier' \
  --data-urlencode 'client_id=client_id' \
  --data-urlencode 'client_secret=client_secret' \
  --data-urlencode 'code=authorization code' \
  --data-urlencode 'redirect_uri=external app redirect uri' \
  --data-urlencode 'grant_type=authorization_code'
Also available for other regions: 
# North America
curl --location --request POST 'https://vantage-us.abbyy.com/auth2/connect/token' \
  --data-urlencode 'code_verifier=code_verifier' \
  --data-urlencode 'client_id=client_id' \
  --data-urlencode 'client_secret=client_secret' \
  --data-urlencode 'code=authorization code' \
  --data-urlencode 'redirect_uri=external app redirect uri' \
  --data-urlencode 'grant_type=authorization_code'

# Australia
curl --location --request POST 'https://vantage-au.abbyy.com/auth2/connect/token' \
  --data-urlencode 'code_verifier=code_verifier' \
  --data-urlencode 'client_id=client_id' \
  --data-urlencode 'client_secret=client_secret' \
  --data-urlencode 'code=authorization code' \
  --data-urlencode 'redirect_uri=external app redirect uri' \
  --data-urlencode 'grant_type=authorization_code'
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:
ParameterDescription
client_idThe application identifier.
client_secretA secure application key.
refresh_tokenYour refresh token obtained from the server.
grant_type=refresh_tokenSpecifies that the refresh token grant type is used.
Sample request (Windows): 
curl --location --request POST "https://vantage-eu.abbyy.com/auth2/connect/token" \
  --data-urlencode "client_id=client_id" \
  --data-urlencode "client_secret=client_secret" \
  --data-urlencode "refresh_token=refresh_token" \
  --data-urlencode "grant_type=refresh_token"
Also available for other regions and Linux with equivalent commands.

​
Token lifetimes

Access and refresh tokens are configured to have the following lifetimes:
  • Access token lifetime: 24 hours. Period of time during which the issued access token is valid.
  • Refresh token lifetime: 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.