Authentication
Access to our API requires authentication. How you authenticate depends on your use case, and if you are a person or an application. Are you:
End users
If you are using a WhenFresh site (custom to you, or using one of our demos), you will need to create a WhenFresh account first. You can do this by accessing our signing-up page.
Once you've provided your details, we will send you a confirmation email. Remember to check your junk folder in your email client!
Click on the link we e-mailed you, and you'll be able to access the site directly.
If your company has a contract with us, remember to use your company e-mail address so you can be enrolled automatically on your corporate account. For more details, contact your administrator.
Developers
The API is designed to support two industry standards for authentication: OAuth 2.0 and OpenID Connect.
Developers also require a WhenFresh account, which they will need to create as described above.
One your account is active, you can go to the My account page to retrieve tokens you will use to connect to the API.
Exploring with access tokens
For interacting quickly with the API, using curl or wget, you can use the access token we generate for you
when you sign-in, it's valid for 60 minutes. You simply pass it as part of the Authentication header, and we provide
you with some sample code for curl on the Token usage page.
Access tokens are only valid for 60 minutes for security reasons: this ensures that anyone that could've gotten hold of that key would automatically be disconnected after the elapsed time.
Implementing refresh tokens
You can think of OAuth as providing you with a master key to enter the bank. It is valid for a long time, and it allows you to enter the premises. Once you are inside the bank, you can show your master key, and exchange it for a temporary one, your access token, and this one is only valid for a short amount of time. This improves security and scalability of your systems, and ours.
We provide you with your developer refresh token on the My account page. You can safely store it in your local developer environment, it is tied to your account.
You exchange that token for the access token by implementing the OAuth authorization code flow. Our .NET SDK takes care of authentication, and if you implement a custom HTTP client, we've documented this in our HTTP Authentication Guide.
Applications
After you have signed a term-sheet with us, we will provide you with App credentials, usually one for your UAT environment, and one for your Live environment, but we can create as many as you wish.
An App Credential is made of a Client ID and a Client Secret. You will then exchange those for an access token, using the OAuth client credentials flow. Again, our .NET SDK takes care of it for you, and if you do it in your own HTTP client, the credentials flow is also documented.