HTTP Quick Start

This quick start guide demonstrates how to authenticate and make a first call to the WhenFresh API via HTTP.

Authenticate

The WhenFresh API uses OpenID Connect to ensure all access to the API is authenticated.

All requests to the API will require an access_token.

Get the token endpoint

To authenticate, first get the token_endpoint from the API's well-known endpoint.

Request:

GET /.well-known/openid-configuration HTTP/1.1
Host: api.whenfresh.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "authorization_endpoint" : "https://id.api.whenfresh.com/oauth2/authorize",
   "token_endpoint" : "https://id.api.whenfresh.com/oauth2/token"
}

You will only need the token_endpoint (not the authorization_endpoint) from this response, since in this case you will be authenticating using the refresh token from your account page rather than authenticating programmatically.

Obtain an access token during development

Your account page provides a refresh token for use during development, which you need to pass to the token_endpoint to get an access_token. Note that the client_id in this request is a fixed value used for developer access to the API via HTTP.

Request:

POST /oauth2/token HTTP/1.1
Host: id.api.whenfresh.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

client_id=r5e6j0k1oevsfgmb9secod9qd&grant_type=refresh_token&refresh_token=[YOUR_REFRESH_TOKEN]

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id_token" : "[YOUR_ID_TOKEN]",
    "access_token" : "[YOUR_ACCESS_TOKEN]",
    "expires_in" : 3600,
    "token_type" : "Bearer"
 }

Obtaining an access token in a deployed environment

When you are ready to deploy your integration into one of your environments we will provide you with a client_id and client_secret specific to that environment. You will need to pass these to the token_endpoint to get an access_token.

Specifically, the client_id and client_secret are passed in as a Base64 encoded Basic Authentication header value. The value is the Base64 of the client_id and client_secret concatenated together with a : character. So for example, if your client_id is abc, and your client_secret is 123, you would pass the following Authorization header: Basic YWJjOjEyMw==.

Request:

POST /oauth2/token HTTP/1.1
Host: id.api.whenfresh.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic Base64([YOUR_CLIENT_ID]:[YOUR_CLIENT_SECRET])

grant_type=client_credentials

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token" : "[YOUR_ACCESS_TOKEN]",
  "expires_in" : 3600,
  "token_type" : "Bearer"
}

The access_token allows authorized access to the API for a limited time (1 hour) and must be passed as the bearer to subsequent API requests.

Verify

In order to test that your access token is valid, we provide a ping test resource.

Request:

GET /dev/null HTTP/1.1
Host: api.whenfresh.com
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Accept: application/json

Response:

For the ping test resource, a successful authorization will result in:

HTTP/1.1 201 OK

An authorization failure will result in:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"message":"Unauthorized"}