Authentication
The vSure Visa Check API uses OAuth2 to authenticate your application. Applications are issued a client_id and a client_secret, and you exchange these credentials securely to receive an access token.
You can then use the access token to make API calls to the Visa Check API. Access tokens will expire over time and can be refreshed.
NOTE: tokens currently have a 24 hour expiry, PLEASE do NOT excessively refresh your tokens. Your account will be disabled if we detect excess token refreshes.
Quickstart
If you're familiar with OAuth2 then this quick start is for you. A more detailed step by step guide is included below.
Access to the sandbox and live environments is gated behind four scopes which you need to request during your authentication: aus:sandbox, aus:live, nzl:sandbox and nzl:live.
For most integrations, you'll have a production and non-production client_id, with corresponding grants on these scopes (i.e. your sandbox application can request aus:sandbox and your production application can request aus:live).
The following configuration values will be required by your application for authentication.
client_id = <provided, per application>
client_secret = <provided, per application>
audience = "https://platform.vsure.com.au/v2"
scopes = "aus:sandbox aus:live"
Step by Step
Types of applications
In this guide, we refer to an 'application'. This represents your integration or solution and is loosely synonymous with the term 'client'.
If your current product/solution runs in an untrusted environment (such as native mobile apps or single page web apps) where you cannot store a secret securely then you will need to provide your own backend to query the vSure Visa Check API. Your untrusted application (mobile app or SPA) will call your backend which can then access the vSure Visa Check API securely.
Credentials & configuration
In most scenarios, you'll be given two different sets of client_id and client_secret. A client_id is considered a public identifier for your application and a client_secret should only ever be shared in a secure way between your application and login.vsure.com.au. In OAuth2 terms, this is our authorization server.
It's recommended you treat both values as secure, configurable variables - so don't hard code them in your solution. Using a cloud based key management solution is considered best practice.
Grant Types & Scopes
vSure uses the OAuth2 standard for authentication and authorisation.
The Visa Check API only supports machine to machine applications, and as a result only uses the "client_credentials" grant type. Clients can additionally use "refresh_token" later on to refresh their access token.
If you are building a web or mobile application, you’ll need to architect around this by making calls to the Visa Check API v2 from your own back-end. Do not call the API from your mobile application directly.
When authenticating using client_credentials, clients additionally provide scopes which act as permissions. The scopes for your application are shown in the developer portal and are referenced in the Scopes section. Currently vSure supports 4 scopes: aus:sandbox, aus:live, nzl:sandbox and nzl:live.
Authentication
The vSure Visa Check API requires an access token in order to authenticate your requests.
An access token request looks like this:
POST /oauth/token HTTP/1.1
Host: https://login.vsure.com.au
Content-Type: application/json
{
"client_id":"your_client_id",
"client_secret":"your_client_Secret",
"audience":"https://platform.vsure.com.au/v2","grant_type":"client_credentials",
"scopes": "aus:sandbox"
}
If completed correctly, the response will be a JSON object with an "access_token" property.
{
"access_token": "ACCESS.TOKEN.HERE",
"expires_in": 86400,
"token_type": "Bearer"
}
Yes, access tokens are JWT's, however you should generally treat them as expiring opaque strings.
Using your Access Token
Now that you have your access token, you can provide it in API calls using the Authorization header like this:
GET /v2/visa-checks HTTP/1.1
Host: platform.vsure.com.au
Authorization: Bearer ACCESS.TOKEN.HERE
Version: 2024-03-04
Note the single whitespace character between "Bearer" and your access token.
Token Expiry
Tokens will expire, and their expiry time can change. Generally speaking however, tokens are valid for several hours (usually 24 hours). The expiry is provided in the token response when you get the access token, and is the number of seconds from when the token is issued to when it expires.
When tokens expire, calls to the API will fail with a 401 error, and a message explaining that the token has expired.
You can request new access tokens before old access tokens expire, allowing you to soft rotate tokens as part of your integration.