Everyone
has at least one set of keys; don’t they? You can recognize your keys and you make
sure you take them wherever you go. Look at each key on your keyring and you know
which door or cabinet it opens (well, we should know anyway). Some of us have
keys we no longer know the purpose of – what we do know is that the lock for
that key is probably useless without it.

API’s and
the content or function they provide can also be protected by one or more keys.
Each key has a purpose and it’s important to understand what each key is for.
The only difference here, is we often refer to these keys as tokens.

API Keys.
These are used to protect the API endpoint from consumption by non-registered
consumers. They are usually issued by an API gateway, who’s responsibility it
is to manage the APIs published via them. API keys are issued to the person or
organization who intends to use the API for their application – this key allows
them to access the API endpoint, but not necessarily access to a user’s data or
to execute a user function behind the endpoint. That’s potentially the purpose
of another key – the JWT (JSON Web Token).

JWT’s can
perform a number of key functions (pun intended). They can be used to provide
the information of an authenticated user as well as their permissions within
the context of their authentication. They can also include custom data and other
values relevant to the API endpoint, including relevant time bounds, issuer,
subject and intended audience of the request.

To ensure JWTs
are URL safe, they are transported as base64 encoded strings. This means that although
they may not seem readable, any decoder can reconstitute them as the characters
they represent (JSON object); well, almost. A single JWT is made up of three
components

  • the header contains information about
    the JWT including the algorithm used to sign it – this part is readable.
  • the body contains the actual payload
    (claims) of the JWT as a JSON object – this part is also readable.
  • the signature of the JWT – this is
    not readable but used to verify that the header and body of the JWT have not
    been tampered with (changed).

It’s
important to understand this – simply because the JWT being sent seems illegible,
does not mean is it. JWTs protect the integrity of the information inside them,
not the visibility. So, please don’t think they can contain sensitive data – that’s
another kind of key; an encrypted JWT or JWE (JSON Web Encryption).

Anyway, we’ve
started to get technical; let’s bring it back up a level.

A JWT carries
the information about what an authenticated user can do, their authorization. This
information is signed using a defined algorithm and a secret key (yep, another
one…), thereby enforcing its integrity. Essentially, we use a JWT to transport information
about the user, their permissions, and any other details about the request in a
way that any changes can be recognized.

In the same
way that we can look at the keys on our keyring and recognize what each is for,
we can also see the contents of a JWT. Like the profile of a key needs to
line-up with the tumblers in a lock in order to open it, the API producer
should use the profile (user and scopes) of the JWT to decide whether access to
the resource should be allowed. If you tamper with the profile of a key, it
will stop opening its corresponding lock. Tamper with the contents of a JWT and
the API producer should not trust it and therefore not allow access.

Finally,
you would not leave your house keys outside your front door, so please don’t leave
your API keys where they can be used.

Photo by PhotoMIX Ltd. from Pexels