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