API User Guide - Visit Singapore Account

Visit Singapore Account APIs

The Visit Singapore Account (VS Account) is a unique digital identity for each visitor to Singapore, to enable Singapore Tourism Board (STB) and our partners, like yourself, to deliver a truly personalised experience to each traveler. You can use the VS Account service as a fast, convenient and secure way for VS Account users to log into your digital application or website.

This guide covers the integration process flow to use the VS Account APIs.

 

Setting Up Your Access to VS Account APIs

To use the VS Account APIs, start by registering for a TIH Business account and request for the service through the following procedure:

  1. The partner shall submit the application form to request for the OAuth key for access to the VS Account APIs with the following key information:

    1. TIH Portal ID refers to the email address used to register for a TIH Business account
    2. Nature of Business
    3. Intended use of VS Account APIs
    4. Application(s) Name, Description and URL
    5. Redirect URL refers to the application's url to redirect the VS Account user to upon successful authorisation
    6. Applicant’s Privacy Policy and Terms of Service URLs
    7. Application administrator’s email address to receive notifications if a user requests to revoke the partner's application permission to access his/her personal data.

     

  2. The partner shall submit all necessary information as may be required by STB in connectionwith their application for the VS Account service. By doing so, the partner warrants that any information, which they have provided in order to obtain the API, is accurate and complete for the duration of their access and/or use of the API. If there is any update to the information provided, they are expected to inform TIH Helpdesk at (stb_tih@stb.gov.sg) immediately.

  3. By requesting for the VS Account service, the partner unconditionally agree to be bound by TIH Terms of Use, which may be updated and amended from time to time at STB’s sole and absolute discretion.

  4. Once the request is approved, an email with the Client Id and Client Secret will be sent to the partner’s email address and application administrator’s email address.

  5. The partner is then able to integrate the VS Account APIs into the specified application(s) by following the specifications captured in this guide.

 

Management of VS Account Users Consent

A VS Account User may withdraw his/her consent for the sharing, use or storage of his/her personal data with a partner’s application. STB will notify the partner of such withdrawal of consent via an email sent to the partner’s administrator email address, stated in the application form submitted to the TIH Helpdesk during onboarding.

The partner shall delete all of the VS Account User's data upon notification by STB if that user requests for such deletion, unless the partner is required to keep it by law.

 

API Interface Overview

The VS Account service APIs are RESTful web services based on representational state transfer (REST) technology, that uses HTTP requests to access data from the VS Account service. The APIs leverages the OAuth 2.0 industry-standard protocol for authorisation and authentication of the VS Account users.

The following provides an overview of the available methods and formats to access the data via the APIs.

The available API endpoints for partners include, but not limited to, the following:

  1. Authentication

    A valid access token is required to access any of the VS Account APIs. Refer to OAuth Authentication Process Flow, tapping on the OAuth 2.0 authorisation framework. The flow first gets a code from the authorisation server, followed by exchange the code for an access token. The code-to-token exchange requires the Client Id and Client Secret.

  2. Request and Response Format

    • The VS Account APIs request and response support only the JSON format. Non-JSON format request will receive error code 406.
    • For API with a POST/PUT/DELETE HTTP method, it is mandatory to indicate "application/json" in the "Content-Type" request header.

  3. Available API Endpoints

 

Integrating with VS Account APIs

The steps to integration are as follows:

OAuth Authentication Process Flow

The OAuth protocol allows the partner's application to access to resource APIs on behalf of a resource owner (i.e. VS Account user) through the use of access tokens.

The following diagram shows the sequence to be authorised to access the VS Account APIs.

 

  • Resource owner refers to the VS Account user, who grants access to the protected resources (e.g. name, email, etc)
  • Resource server refers to the server hosting the VS Account data of the resource owner.
  • Client refers to the partner's application requesting access to the resource server (e.g. mobile or web app)
  • Authorisation server refers to the server issuing access token to the client. This token is for the client to request for access to the resources in the resource server, and there are 2 types:
    • Access Token

      This token is sent by the client as a header in the request to the resource server. It has a limited lifetime, which is defined in the API response.

    • Refresh Token

      This token is issued with the access token. If the client needs access to the VS Account APIs beyond the lifetime of a single access token, the client can refresh the access token before the access token expires.

 

 

Get Authorisation Code

Now that you have registered for a TIH Business account and the application,

  1. Implement a login button, in accordance to the design guidelines and connect the button to the VS Account Portal using the following url: https://account.visitsingapore.com/sso/oauth2.0/authorize?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&response_type=code

    Where:

    • CLIENT_ID is issued upon successful registration for a TIH Business account .
    • REDIRECT_URI is the application's url to redirect the VS Account user to upon successful authorisation.

  2. Upon clicking on the login button, it redirects to VS Account Portal Login page for the resource owner’s login credentials. Apart from email login, VS Account also enables login via social handle (e.g. Facebook), in which the resource owner is expected to have an existing account with the associated platforms. In the event that the resource owner has to register for a social handle, the resource owner will not be auto redirected to the VS Account Portal.

  3. On successful login, the resource owner will be prompted for consent to share his/her profile information with the client.

  4. With the resource owner’s consent, it redirects to the REDIRECT_URI specified in the above url with the authorization code appended to it (e.g. https://[REDIRECT_URI]?code=).

    • Authorisation code will have the following format:
      • Alphanumeric characters
      • hyphen “-” as the only allowed special character
    • In cases where the resource owner logs in via a social handle, the returned URI may be appended with an additional hash (e.g. #_=_). The client will have to remove the hash, highlighted in this example, from the authorisation code before use (e.g.https://[REDIRECT_URI]?code=#_=_).

     

 

Get Access Token

Now that you have the authorisation code from the Get Authorisation Code step, proceed to exchange the code for the access token.

  1. Call the VS Account OAuth API with the authorisation code, using POST HTTP method, and the following values for the request parameters:
    Request Headers Content-Type: application/json
    Query Parameters

    client_id=[CLIENT_ID]

    client_secret=[CLIENT_SECRET]

    redirect_uri=[REDIRECT_URI]

    grant_type=authorization_code

    code=[AUTH_CODE], where AUTH_CODE is from the Get Authorisation Code step

  2. The response will have token type, access token, refresh token and the expiry duration of the access token.

 

Refresh Access Token

Generate a new access token, using the refresh token.

  1. Call the VS Account OAuth API, using POST HTTP method, and the following values for the request parameters:
    Request Headers Content-Type: application/json
    Query Parameters

    client_id=[CLIENT_ID]

    client_secret=[CLIENT_SECRET]

    redirect_uri=[REDIRECT_URI]

    grant_type=refresh_token

    refresh_token=[REFRESH_TOKEN], where REFRESH_TOKEN is from the Get Access Token step
  2. The response will have token type, access token and the expiry duration of the access token.

 

Access the VS Account APIs

The access token from the Get Access Token step can be used to access the VS Account APIs to retrieve VS Account users' data. Get started today!

 

VisitSingapore

Visit Singapore Account

Allow your visitor to log in to your app faster for a seamless experience.

View APIs

 

Design Guidelines on the VS Account Sign-in Button

Visit Singapore Account sign-in button should be applied across your application or website consistently.

The composition of the button contains two key elements:

  1. Passion Made Possible logo
  2. Red rectangle button with white text “Log in with Visit Singapore”

The Visit Singapore Account sign-in button must be used as-is. It should be legible and displayed as prominently as other third-party sign-in options, if applicable.

To seek deviations from the guidelines, please write to the TIH Helpdesk (stb_tih@stb.gov.sg) for approval. STB reserves the right not to approve deviations and/or revoke the use of the Visit Singapore Account sign-in button.