Volante Authentication API

1. Overview

The Authentication API enables you to manage all aspects of user identity when you use Volante’s product API Services. It offers an endpoint to generate and refresh the Access Token and it must be passed into every request to the Volante’s product API endpoints.

The OpenAPI (aka Swagger) Specification, which is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services, is available in the following location:

OpenAPI : Volante Authentication API

2. Authentication

API access to the Volante’s product API endpoints are protected by an Access Token. To generate the Access Token, you must make a request to Get Access Token endpoint by passing client Id, client secret and org-url-prefix which you received during the on-boarding process.

During the organization or user onboarding process, the final confirmation email contains below information. Make sure to replace below parameters with your data.

Param	Example	Comments
authorization URL	https://sandbox.volantetech.com/auth/abc-bank	use URL mentioned in the onboarding email.
client Id	12dcf3ba-fc84-451f-8efc-a0bdfa451343	use Client Id mentioned in the Onboarding email.
client Secret	FvMVY2GiOA6bpll3diBfoZDa4r5R7evZ	use Client Secret mentioned in the Onboarding email.
org-url-prefix	abc-bank	This can be obtained from the authorization URL.

Param

Example

Comments

authorization URL

https://sandbox.volantetech.com/auth/abc-bank

use URL mentioned in the onboarding email.

client Id

12dcf3ba-fc84-451f-8efc-a0bdfa451343

use Client Id mentioned in the Onboarding email.

client Secret

FvMVY2GiOA6bpll3diBfoZDa4r5R7evZ

use Client Secret mentioned in the Onboarding email.

org-url-prefix

abc-bank

This can be obtained from the authorization URL.

Volante’s Product API services expects the Access Token to be included in all the API requests to the server in an Authorization header that looks like the below,

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiS

2.1. How it works

localImage

To generate access token

curl -X POST https://sandbox.volantetech.com/auth/abc-bank -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=12dcf3ba-fc84-451f-8efc-a0bdfa451343&client_secret=FvMVY2GiOA6bpll3diBfoZDa4r5R7evZ"

To access Product API

curl -X GET https://sandbox.volantetech.com/iso20022/v2/validator/catalog -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI"

To refresh access token

curl -X POST https://sandbox.volantetech.com/auth/volantetech-volx -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&client_id=12dcf3ba-fc84-451f-8efc-a0bdfa451343&client_secret=FvMVY2GiOA6bpll3diBfoZDa4r5R7evZ&refresh_token=eyJhbGciOiJIUzI1NiIsInR5"

3. General Information

3.1. Version information

Version : 1.0

3.2. URI scheme

Host : sandbox.volantetech.com:443
Schemes : HTTPS

3.3. Tags

Get Access Token

4. Resources

4.1. Get Access Token

4.1.1. Get Access Token

POST /auth/{org_url_prefix}

Description

This endpoint is used for generating access token and refresh token. Generated access token should be passed as a authorization bearer token. Incase of generating access token, pass clientId, clientSecrent and grant type would be client_credentials. Incase of refresh_token, pass grant_type as refresh_token, refresh_token along with valid client id and client secret. The Get Access Token and Refresh Token endpoint is a specific endpoint used in OAuth 2.0-based authentication flows to obtain an access token and a refresh token. This endpoint is typically provided by the authorization server, and is used by client applications to request both an access token and a refresh token after the user has granted permission to the application. The Get Access Token and Refresh Token endpoint typically accepts a set of parameters as part of the request, including the client ID, client secret, authorization code, redirect URI, and any required scopes. The endpoint then validates the parameters, and if everything is in order, returns both an access token and a refresh token in the response body. The access token can be used by the client application to access protected resources on behalf of the user, while the refresh token can be used to obtain a new access token when the original token expires. The Get Access Token and Refresh Token endpoint is typically secured using HTTPS, and may require authentication of the client application using a client ID and secret or other credentials. The exact format and structure of the request and response parameters may vary depending on the specific OAuth 2.0 implementation being used, as well as any customizations or extensions that have been added to the protocol. However, the basic principles of requesting and obtaining an access token and refresh token through the Get Access Token and Refresh Token endpoint are consistent across most OAuth 2.0-based authentication flows.

Parameters

Type	Name	Description	Schema
Path	org_url_prefix required	In the context of authentication and authorization, a org_url_prefix is a string value that is used to identify a protected resource or set of resources. It is typically included as part of the challenge response in HTTP-based authentication protocols such as Basic and Digest authentication.	string
FormData	client_id required	A client ID is a unique identifier that is assigned to a client software application or a web application by a server or an authorization server. The client ID is used to identify the client application when making requests to the server. In the context of web development, a client ID is commonly used in OAuth 2.0 and OpenID Connect authentication protocols. When a user wants to access a protected resource on a server, the user’s client application must first obtain an access token from the server. The client ID is one of the parameters that the client application must include in the request for the access token. The server uses the client ID to authenticate the client application and to determine whether the application is authorized to access the requested resource. In general, a client ID is a unique identifier that is used to identify a client application in various contexts, including software development, web development, and network protocols.	string
FormData	client_secret required	A client secret is a confidential value that is used to authenticate a client application to a server or an authorization server. It is a shared secret between the client application and the server, and it is intended to be known only by the client application and the server. In the context of web development, a client secret is often used in OAuth 2.0 and OpenID Connect authentication protocols. When a client application requests an access token from a server, it includes the client secret as a parameter in the request. The server uses the client secret to authenticate the client application and to verify that the application is authorized to access the requested resource. The client secret is typically stored securely on the client application’s server and is not disclosed to the end user or to other third parties. The client secret should be protected carefully, and it should not be included in client-side code or in public repositories. In general, a client secret is a secure value that is used to authenticate a client application to a server, and it is an important component of many authentication protocols.	string
FormData	refresh_token optional	This is mandatory property in refresh_token grant_type. A refresh token is a type of token used in OAuth 2.0 authentication that allows a client application to obtain a new access token without requiring the user to re-authenticate. When a user first authenticates a client application with a server, the server issues both an access token and a refresh token. The access token is used to authenticate the user to access protected resources, while the refresh token is used to obtain a new access token when the original access token expires or becomes invalid. When the access token expires, the client application can use the refresh token to request a new access token from the server, without requiring the user to re-authenticate. The server verifies the refresh token and issues a new access token to the client application. Refresh tokens are typically longer-lived than access tokens and can be revoked by the server at any time. Refresh tokens should be stored securely on the client application’s server, and they should not be included in client-side code or in public repositories. In summary, refresh tokens are used to obtain new access tokens without requiring the user to re-authenticate, and they are an important component of many OAuth 2.0 authentication flows.	string
FormData	grant_type required	Based on the scenario, grant_type can be either client_credentials or refresh_token. Based on the scenario, refresh_token can be mandatory. The server then uses the grant type to determine the appropriate authentication and authorization flow to use.	string

Type

Name

Description

Schema

Path

org_url_prefix
required

In the context of authentication and authorization, a org_url_prefix is a string value that is used to identify a protected resource or set of resources. It is typically included as part of the challenge response in HTTP-based authentication protocols such as Basic and Digest authentication.

string

FormData

client_id
required

A client ID is a unique identifier that is assigned to a client software application or a web application by a server or an authorization server. The client ID is used to identify the client application when making requests to the server. In the context of web development, a client ID is commonly used in OAuth 2.0 and OpenID Connect authentication protocols. When a user wants to access a protected resource on a server, the user’s client application must first obtain an access token from the server. The client ID is one of the parameters that the client application must include in the request for the access token. The server uses the client ID to authenticate the client application and to determine whether the application is authorized to access the requested resource. In general, a client ID is a unique identifier that is used to identify a client application in various contexts, including software development, web development, and network protocols.

string

FormData

client_secret
required

A client secret is a confidential value that is used to authenticate a client application to a server or an authorization server. It is a shared secret between the client application and the server, and it is intended to be known only by the client application and the server. In the context of web development, a client secret is often used in OAuth 2.0 and OpenID Connect authentication protocols. When a client application requests an access token from a server, it includes the client secret as a parameter in the request. The server uses the client secret to authenticate the client application and to verify that the application is authorized to access the requested resource. The client secret is typically stored securely on the client application’s server and is not disclosed to the end user or to other third parties. The client secret should be protected carefully, and it should not be included in client-side code or in public repositories. In general, a client secret is a secure value that is used to authenticate a client application to a server, and it is an important component of many authentication protocols.

string

FormData

refresh_token
optional

This is mandatory property in refresh_token grant_type. A refresh token is a type of token used in OAuth 2.0 authentication that allows a client application to obtain a new access token without requiring the user to re-authenticate. When a user first authenticates a client application with a server, the server issues both an access token and a refresh token. The access token is used to authenticate the user to access protected resources, while the refresh token is used to obtain a new access token when the original access token expires or becomes invalid. When the access token expires, the client application can use the refresh token to request a new access token from the server, without requiring the user to re-authenticate. The server verifies the refresh token and issues a new access token to the client application. Refresh tokens are typically longer-lived than access tokens and can be revoked by the server at any time. Refresh tokens should be stored securely on the client application’s server, and they should not be included in client-side code or in public repositories. In summary, refresh tokens are used to obtain new access tokens without requiring the user to re-authenticate, and they are an important component of many OAuth 2.0 authentication flows.

string

FormData

grant_type
required

Based on the scenario, grant_type can be either client_credentials or refresh_token. Based on the scenario, refresh_token can be mandatory. The server then uses the grant type to determine the appropriate authentication and authorization flow to use.

string

Responses

HTTP Code	Description	Schema
200	OK	token_response
400	Bad Request	error_response
401	Unauthorized	error_response
404	Realm Not Found	error_response
500	Internal Server Error	error_response

HTTP Code

Description

Schema

200

token_response

400

Bad Request

error_response

401

Unauthorized

error_response

404

Realm Not Found

error_response

500

Internal Server Error

error_response

Consumes

application/x-www-form-urlencoded
multipart/form-data
multipart/mixed

Produces

application/json
application/xml

5. Definitions

5.1. token_response

Name	Description	Schema
access_token optional	An access token is a type of security credential that is used to authenticate a client application to access protected resources on a server. It is a string of characters that is generated by a server and is used by a client application to make authorized requests to access protected resources.	string
expires_in optional	The expires_in parameter is a field in OAuth 2.0 authorization responses that specifies the lifetime of an access token in seconds. When an access token is issued by an authorization server, it is typically only valid for a certain period of time, after which it expires and can no longer be used to access protected resources. The expires_in field specifies the duration of time in seconds that the access token will remain valid.	integer
refresh_expires_in optional	The refresh_expires_in parameter is a field used in some OAuth 2.0 implementations to specify the lifetime of a refresh token in seconds. A refresh token is a credential that is used by a client application to obtain a new access token after the original access token has expired. The refresh token is typically issued along with the access token by the authorization server. The refresh_expires_in field specifies the duration of time in seconds that the refresh token will remain valid. When the refresh token expires, the client application will need to re-authenticate and obtain a new set of access and refresh tokens.	integer
refresh_token optional	A refresh token is a type of token used in some OAuth 2.0 authentication flows to obtain a new access token without requiring the user to re-authenticate. When a user first authenticates a client application with a server, the server issues both an access token and a refresh token. The access token is used to authenticate the user to access protected resources, while the refresh token is used to obtain a new access token when the original access token expires or becomes invalid.	string
token_type optional	The token_type parameter is used in some OAuth 2.0 and OpenID Connect implementations to specify the type of token being returned in a response. When a client application requests an access token from an authorization server, the server may issue an access token that is a bearer token, a JSON Web Token (JWT), or some other type of token. The token_type parameter specifies the type of token that is being returned in the response, and it can be used by the client application to determine how to use the token.	string
not-before-policy optional	not-before-policy is a security feature used in some authentication systems to limit the time when certain actions can be performed. It is commonly used in conjunction with access tokens or other types of security tokens to ensure that they cannot be used until a certain time has passed. The not-before-policy is a timestamp that specifies the earliest time at which a token or credential can be used.	integer
session_state optional	In the context of web authentication protocols such as OpenID Connect, a session state is a security parameter that is used to protect against certain types of attacks, such as Cross-Site Request Forgery (CSRF) attacks. The session state is typically a random value that is generated by the authorization server when the user first authenticates with the server. The value is then included in the response to the client application along with the access token and other parameters. The client application is expected to maintain this value and return it to the server with subsequent requests to help prevent CSRF attacks.	string
scope optional	In the context of authentication and authorization protocols like OAuth 2.0, a scope is a parameter that defines the level of access and permissions granted to a client application by a resource owner.	string

Name

Description

Schema

access_token
optional

An access token is a type of security credential that is used to authenticate a client application to access protected resources on a server. It is a string of characters that is generated by a server and is used by a client application to make authorized requests to access protected resources.

string

expires_in
optional

The expires_in parameter is a field in OAuth 2.0 authorization responses that specifies the lifetime of an access token in seconds. When an access token is issued by an authorization server, it is typically only valid for a certain period of time, after which it expires and can no longer be used to access protected resources. The expires_in field specifies the duration of time in seconds that the access token will remain valid.

integer

refresh_expires_in
optional

The refresh_expires_in parameter is a field used in some OAuth 2.0 implementations to specify the lifetime of a refresh token in seconds. A refresh token is a credential that is used by a client application to obtain a new access token after the original access token has expired. The refresh token is typically issued along with the access token by the authorization server. The refresh_expires_in field specifies the duration of time in seconds that the refresh token will remain valid. When the refresh token expires, the client application will need to re-authenticate and obtain a new set of access and refresh tokens.

integer

refresh_token
optional

A refresh token is a type of token used in some OAuth 2.0 authentication flows to obtain a new access token without requiring the user to re-authenticate. When a user first authenticates a client application with a server, the server issues both an access token and a refresh token. The access token is used to authenticate the user to access protected resources, while the refresh token is used to obtain a new access token when the original access token expires or becomes invalid.

string

token_type
optional

The token_type parameter is used in some OAuth 2.0 and OpenID Connect implementations to specify the type of token being returned in a response. When a client application requests an access token from an authorization server, the server may issue an access token that is a bearer token, a JSON Web Token (JWT), or some other type of token. The token_type parameter specifies the type of token that is being returned in the response, and it can be used by the client application to determine how to use the token.

string

not-before-policy
optional

not-before-policy is a security feature used in some authentication systems to limit the time when certain actions can be performed. It is commonly used in conjunction with access tokens or other types of security tokens to ensure that they cannot be used until a certain time has passed. The not-before-policy is a timestamp that specifies the earliest time at which a token or credential can be used.

integer

session_state
optional

In the context of web authentication protocols such as OpenID Connect, a session state is a security parameter that is used to protect against certain types of attacks, such as Cross-Site Request Forgery (CSRF) attacks. The session state is typically a random value that is generated by the authorization server when the user first authenticates with the server. The value is then included in the response to the client application along with the access token and other parameters. The client application is expected to maintain this value and return it to the server with subsequent requests to help prevent CSRF attacks.

string

scope
optional

In the context of authentication and authorization protocols like OAuth 2.0, a scope is a parameter that defines the level of access and permissions granted to a client application by a resource owner.

string

5.2. error_response

Name	Schema
success optional	boolean
errors optional	< errors > array

Name

Schema

success
optional

boolean

errors
optional

< errors > array

errors

Name	Schema
severity optional	string
code optional	string
message optional	string

Name

Schema

severity
optional

string

code
optional

string

message
optional

string