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"}