Authentication
Each HTTP request to the service should include an authorization header that ABBYY Vantage will use to confirm your identity. Contact ABBYY to request a tenant in ABBYY Vantage service. Once you have a tenant's account, you can create user accounts. The user account's e-mail and password can be used to get an access token for API authorization.
The OAuth 2.0 protocol is used in ABBYY Vantage for authentication. OAuth 2.0 authentication is carried out over two stages: getting an access token and then the authorization itself.
Access tokens can be obtained using two standard authentication schemes: Resource Owner Password Credentials and Authorization Code Flow.
OpenID Connect Discovery Document
You can set up your application using OpenID Connect (OIDC) Discovery Document located at https://vantage-eu.abbyy.com/auth2/{tenantId}/.well-known/openid-configuration (for users in Western Europe), https://vantage-us.abbyy.com/auth2/{tenantId}/.well-known/openid-configuration (for users in North America), and https://vantage-au.abbyy.com/auth2/{tenantId}/.well-known/openid-configuration (for users in Australia). For information about obtaining a tenant identifier, see the Getting a Tenant Identifier section of the Administrator's guide.
Sample request
We also recommend using URL's found in the discovery document for ROPC and Authorization Code Flows.
Resource Owner Password Credentials
This authentication scheme is relatively simple and allows the application to log into the user's system without having to use the browser by directly processing the username and password instead.
To obtain the access token, 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),
Important! If your email address is connected to several accounts in different tenants and you use Resource Owner Password Credentials authentication, use the following resource: https://vantage-eu.abbyy.com/auth2/{tenantId}/connect/token (for users in Western Europe), https://vantage-us.abbyy.com/auth2/{tenantId}/connect/token (for users in North America), and https://vantage-au.abbyy.com/auth2/{tenantId}/connect/token (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 |
|---|---|
| grant_type=password | Specifies that the password grant type is used. |
| scope=openid permissions global.wildcard | Specifies the permission scope. |
| username and password | Your credentials. |
| client_id |
Application identifier. For information on how to create a REST API Client (client_id and client_secret), see the Managing Tenant REST API Clients article. |
| client_secret |
Secure application key. For information on how to create a REST API Client (client_id and client_secret), see the Managing Tenant REST API Clients article. |
Important! The values for grant_type, scope should be exactly as specified above. These keys are subject to change. Please put them in your configuration files, so that you can easily change them without rebuilding your entire integration.
Sample request:
For Windows
For Linux
The server's response to your request will contain the access token:
Response
For more information about Resource Owner Password Credentials, visit this link.
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
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 REST API Client (client_id and client_secret), see the Managing Tenant REST 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. |
Important! 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 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 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 Vantage REST 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 REST 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 REST API Client (client_id and client_secret), see the Managing Tenant REST API Clients article. |
| client_secret |
Secure application key. For information on how to create a REST API Client (client_id and client_secret), see the Managing Tenant REST 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. |
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). 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.
06.09.2022 16:21:49