Documentation
Documentation
Home

Authentication

Sandbox & Production Environment

Plum Guide maintains a Sandbox Environment in addition to the Production environment. The Sandbox Environment contains a small amount of sample listing data and is intended to be used when developing and testing your integration.

You will have been provided with separate credentials for both the Sandbox and Production environments. The credentials for the Production environment will be given to you once your integration is complete.

All endpoints on the Plum Guide API are secured and need valid authorisation before accessing them. Requests can be authorised by adding a valid token to the call. A token must be generated using your client credentials (consisting of a client ID and client secret) which will have been provided to you. You will have tokens for both the Sandbox and Production environments.

Authentication is done via our authenticate endpoint.

When making requests to the different environments you will need to use the corresponding server. Token Request with Sandbox credentials will only return Tokens that are valid for Sandbox, and similarly, token Request with Production credentials will only return Tokens valid for Production.

How to generate a token

Below are some example requests for authenticating:

curl -X POST "https://sandbox.api.plumguide.com/authenticate" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"clientId\":\"YOUR CLIENT ID\",\"clientSecret\":\"YOUR CLIENT SECRET\"}"

var restClient = new RestClient("https://sandbox.api.plumguide.com/authenticate");
var request = new RestRequest(Method.POST) { RequestFormat = DataFormat.Json };

request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("grant_type", "client_credentials");
request.AddParameter("client_id", "{YOUR CLIENT ID}");
request.AddParameter("client_secret", "{YOUR CLIENT SECRET}");

$.ajax({
  type: "POST",
  url: "https://sandbox.api.plumguide.com/authenticate",
  contentType: "application/x-www-form-urlencoded",
  dataType: "json",
  data: {    
    grant_type: "client_credentials",
    client_id: "{YOUR CLIENT ID}",
    client_secret: "{YOUR CLIENT SECRET}"
  }
});

Capture the request response

The response will be in the following format:

{
  "token": "Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Ijc2MUM4MzQ4Q0U0OTcwMjU2MkYwOERCOTA4MkE4NzYxMUQzNTMyMTkiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJkaHlEU001SmNDVmk4STI1Q0NxSFlSMDFNaGsifQ.eyJuYmYiOjE1ODc5NzQ4MTQsImV4cCI6MTU4Nzk3ODQxNCwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaS5wbHVtZ3VpZGUuY29tIiwiYXVkIjpbImh0dHBzOi8vYXV0aC5hcGkucGx1bWd1aWRlLmNvbS9yZXNvdXJjZXMiLCJwbHVtLWFwaXMiXSwiY2xpZW50X2lkIjoiZmFlc2VsLnRlc3QiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL2FjY2Vzc2NvbnRyb2xzZXJ2aWNlLzIwMTAvMDcvY2xhaW1zL2lkZW50aXR5cHJvdmlkZXIiOiJwbHVtLmlkZW50aXR5Iiwic3ViIjoiMzZkODA3YmUtYjBlNi00ODcxLWFjZjItZTJkMzY4OTI3OWE0IiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiQ21zU2FsZXNmb3JjZU1hbmFnZXIiLCJzY29wZSI6WyJmdWxsX2FjY2VzcyJdfQ.ovmQmFbFeo8zax1S7jFY4u3ICVOMYl_GQlFz4mW28gx1Jpt3e5XTAktpGomHSrD0yJmfETqmUHnZnFvBId--CXHdxy4OUA4LCDzhjsd9pUhuvcPvvh8FAHpn4q2LRTwobbfTrRPv4yMUwIBPZEdMj_1AVwmgMgxml92-pM0Zr_u4FiH2eyEZ7UVAuaQ0Gb7QuBGD2wpDR_7k-uxHYUp60ax20CEv82j4NSwREuFYrMkbl0H0EFzyyTzoj7r-qPNYAXrHYsdOic5ngNBsHwP2MmoKgD5vkPzXqkvsY-WOv5-Im4n7rpZPdRj1KBfudrNS2S2CE22GexjDjoXi3NFp0Q",
  "expiresIn": 3600
}

In the example above, the token parameter contains your access token that needs to be sent with every request you make. Along with the token we also return back the expiry timeframe "expiresIn", this indicates the timeframe (in seconds) in which your token will expire.

Using the generated token

Once the token is generated, it needs to be attached to each subsequent REST call in order to be authenticated. This token needs to be attached as a request header with the following format:

Key: “Authorization”
Value: “{TokenType} {TokenValue}“ // Ex: “Bearer 12xewx=

var restClient = new RestClient("https://api.plumguide.com/listings");
var restRequest = new RestRequest(Method.GET);
restRequest.AddHeader("Authorization", "{TOKEN_TYPE} {ACCESS_TOKEN}");    
var response = restClient.Execute(restRequest);

$.ajax({
    type: "GET",
    url: "https://api.plumguide.com/listings",
    contentType: "application/json; charset=utf-8",
    dataType: "json",
    beforeSend: function (xhr) {
        xhr.setRequestHeader ("Authorization", {TOKEN_TYPE} + ' ' + {ACCESS_TOKEN});
    }
});

Who are you authenticating as

When authenticating on Plum Guide, you will always be authenticated on behalf of a single individual host. Due to this the access you have will be limited to the scope of the host. This means you will only have access to the Listings owned by the host, and in turn the bookings generated from those Listings. When generating requests across multiple hosts, you will need to generate a new access token for each individual host.