vSure Visa Checks API v2

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.

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.

Authentication

The vSure Visa Check API requires an access token in order to authenticate your requests.

An access token request looks like this:

POST /token HTTP/1.1

Host: 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.