Staging & Production Environment
Plum Guide has two environments:
- Staging: https://api.stg.plumguide.io. Use it while you build and test your integration. It holds sample data, and it is the only place where you can create test bookings (see Test Bookings).
- Production: https://api.plumguide.com. This is the live platform.
You get separate credentials for each environment. We send you the Production credentials once your integration is complete.
Every endpoint needs a valid token. You get a token from the authenticate endpoint, using your client credentials (a client ID and a client secret):
- Staging:
POST https://api.stg.plumguide.io/authenticate - Production:
POST https://api.plumguide.com/authenticate
Staging credentials only give tokens for Staging. Production credentials only give tokens for Production.
How to generate a token
Send the client ID and client secret as JSON:
curl -X POST "https://api.stg.plumguide.io/authenticate" \
-H "Content-Type: application/json" \
-d '{"clientId":"YOUR CLIENT ID","clientSecret":"YOUR CLIENT SECRET"}'var client = new HttpClient();
var response = await client.PostAsJsonAsync(
"https://api.stg.plumguide.io/authenticate",
new { clientId = "YOUR CLIENT ID", clientSecret = "YOUR CLIENT SECRET" });
var token = await response.Content.ReadFromJsonAsync<TokenResponse>();const response = await fetch("https://api.stg.plumguide.io/authenticate", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ clientId: "YOUR CLIENT ID", clientSecret: "YOUR CLIENT SECRET" })
});
const { token, expiresIn } = await response.json();If the client ID or secret is missing or wrong, the endpoint returns 400 with a body like this:
{
"AuthenticationError": ["Error authenticating. Please check your credentials."]
}Capture the response
A successful response looks like this:
{
"token": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleGFtcGxlIn0.signature",
"expiresIn": 3600
}tokenis your access token. It already starts withBearer.expiresInis how many seconds the token stays valid. The value can differ between clients, so always read it instead of assuming one hour.
Reuse the token
Get one token for each host, and reuse it for every call until shortly before it expires. Then get a new one. Also get a new one if a call returns 401.
Do not call /authenticate before every request. A sync that authenticates for every update makes many token requests in a few seconds, and gains nothing.
Using the token
Send the token value, unchanged, in the Authorization header of every request:
Authorization: Bearer eyJhbGciOi...Do not add another Bearer in front of it. A header like Bearer Bearer eyJ... returns 401.
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.stg.plumguide.io/v2/listings");
request.Headers.TryAddWithoutValidation("Authorization", token); // token already starts with "Bearer "
var response = await client.SendAsync(request);const listings = await fetch("https://api.stg.plumguide.io/v2/listings", {
headers: { Authorization: token } // token already starts with "Bearer "
});Who are you authenticating as
A token always acts for one host. You can only reach the Listings that host owns, and the bookings and conversations of those Listings. To work with several hosts, get a separate token for each host.
