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 allow customer to authenticate and ensure all access to the API is secure.

Requests always 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.

Developer authentication (Authorisation Code flow)

sequenceDiagram
    actor UA as User Agent
    participant Conf as OIDC Configuration
    participant Token as OAuth TOKEN
    note over UA,Conf: Once on startup, cached
    UA->>Conf: GET
    activate Conf
    note right of Conf: TTLB ≈ 150ms
    Conf-->>UA: Token URI
    deactivate Conf
    note over UA,Token: When no access token, or token expired<br/>Once every 60 minutes (can be customized)
    UA->>Token: POST refresh_token
    activate Token
    note right of Token: TTLB ≈ 80-200ms
    Token-->>UA: ID and Access Token
    deactivate Token

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.

for a developer account are retrieved from the "My Tokens" page and stored on the developer's machine.

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

Machine authentication (Client Credentials flow)

sequenceDiagram
    actor UA as User Agent
    participant Conf as OIDC Configuration
    participant Token as OAuth TOKEN endpoint
    note over UA,Conf: Once on startup, cached
    UA->>Conf: GET
    activate Conf
    note right of Conf: TTLB ≈ 150ms
    Conf-->>UA: Token URI
    deactivate Conf
    note over UA,Token: When no access token, or token expired<br/>Once every 60 minutes (can be customized)
    UA->>Token: POST client id + client secret
    activate Token
    note right of Token: TTLB ≈ 100-200ms<br/>SLA: AWS Cognito
    Token-->>UA: Access Token
    deactivate Token

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