Authenticating with the API

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.