Authentication
The Freezerworks API requires authentication for all requests. This helps protect your data by ensuring all of your Freezerworks security and permissions are enforced.Authentication vs Authorization
While the two terms sound similar and are often confused there is an important difference.
Authentication is the process of identifying a user. It answers the question "Are you who you say you are?". This is essentially the first thing Freezerworks does for every request it receives.
Authorization is the process of checking permissions to see if the user is allowed to do what they want to do. This is the second thing Freezerworks checks for each request.
Somewhat confusingly, API requests will use the Authorization header to send our authentication information.
Types of Authentication
Bearer Token Authentication
By default, Freezerworks uses bearer tokens for authentication. In this configuration, every API request will require an Authorization header that starts with the word 'Bearer' and includes a valid JWT token.
Authorization: Bearer eyJhbGc9.WIiOMzfQ.p7f4MTQ7
JSON Web Tokens (JWTs)
Freezerworks uses a specific type of bearer token known as a JSON Web Token or JWT (pronounced "jot"). A JWT is a long string of text that acts like proof of identity to the API. The JWT is cryptographically signed so that the Freezerworks server can verify that it is authentic. If someone tried to submit a modified JWT the signature would not match and Freezerworks would reject the token. This allows the API to send a JWT to the API user and for that user to view the data in the JWT while preventing a bad actor from manipulating the JWT to gain access.
As a Freezerworks API user, it is never necessary to create, modify, or even open and read the contents of the JWT Freezerworks provides. When a JWT is provided by the API it is returned as part of a standard Siren response object which includes all the details within the JWT for easy review and use. All the API requires is that the JWT is returned with every response to authenticate the user.
The JWT itself is protected from modification. The server can only tell if the token is valid. It cannot tell if a valid token is being supplied by a bad actor. For this reason we recommend that tokens have short life spans (5 minutes by default) and provide a mechanism within Freezerworks to invalidate all existing tokens. We also generate a new secret key for the cryptography on every server restart. These are all in an attempt to mitigate the effects of a token being used by someone other than the intended user.
JWT Structure
A JWT is built in three parts: a header, a payload, and a signature. Each of the three parts is Base64 URL encoded to make it safe to transmit as plain text in HTTP headers. Each of the parts is separated by a period ".". The firt two strings, header and payload, are reversible using the Base64 decoding functions of any programming language.
HeaderThe header contains information about the JWT itself: the type of token and the algorithm used in the signature. This information is JSON formatted.
{
"alg": "HS256",
"typ": "JWT"
}
This information is Base64 URL encoded with extra padding removed: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
PayloadThe payload contains the information provided by the server. In Freezerworks this is limited to the 'sub' (subject) which is the same as the Freezerworks User ID and 'exp' (expiration) which is in seconds since the epoch (Jan 1, 1970).
{
"sub": 100001,
"exp": 2764886400
}
This gets Base64 URL encoded as above: eyJzdWIiOjEwMDAxLCJleHAiOjI3NjQ4ODY0MDB9
SignatureFor the signature, Freezerworks looks uses the other two parts to create a unique string of characters. It uses this string to ensure that the JWT was not modified after being signed.
When combined a full JWT might look something like this: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEwMDAxLCJleHAiOjI3NjQ4ODY0MDB9.8pRvBwtcC08RIBFEYkb1K6aQsCiv82-fMAnhiiG0cms
The JWT is sent with the API request in the Authorization header as shown above.
Basic Authentication
With basic authentication you send your username and password with every API request. The values are sent in the 'Authentication'. The value of the header is a string that starts with 'Basic ' and is followed by a Base64 encoded string of the format username:password. For example, for a username of 'aUser' and a password of 'mySecret' the header would look like this:
Authorization: Basic YVVzZXI6bXlTZWNyZXQ=
The Base64 encoded string can be reversed by anyone that can intercept the request. For this reason it is critical for security that all requests using Basic authentication are made only over secure connections with HTTPS.
SAML
With SAML, the authentication is handled by your organizations identity provider (IdP) outside Freezerworks. The IdP will authenticate the request and then send the request to the service provider (SP) in the custom header configured in Freezerworks. As an example, the IdP may send this header to the SP to allow the user 'Demo' to access the API.X-FWX-SAMLID: demo