All you need to know about API tokens

From basic authentication to the OAuth standard: what are API tokens

  • Author: Alessandra Caraffa
  • //
  • Date: 21/06/2022
  • //
  • Reading time: 3 min

APIs, Application Programming Interfaces, were created for the purpose of exposing proprietary data and functions to third parties: the enormous potential of the tool is therefore inevitably matched by the risks arising from an unaware exposure of data.

The combination of OAuth authentication and SSL certificates, on the other hand, offers the most advanced available in terms of system security. To better understand what this is all about, let us start with one of the pivotal elements of the API-driven architecture, the one that allows the transition from a basic form of authentication to the OAuth standard, the first step towards a Zero Trust architecture.

Let us see what an API token is and how it works, and what are the best practices for generating and managing one's own access keys while limiting the risks associated with exposing data via APIs.

API and Information Security

According to industry analysts, careless use of APIs could quickly turn into the preferred gateway for cyber attacks (Gartner, 2021). The rapid spread of APIs and API-driven architectures can lead software as much as companies to expose themselves, via their web applications, to major security holes, which can uncover up to 40 per cent more of the 'flank' to be protected (Gartner, 2019).

The problem does not stem from a lack of resource security: thanks to encrypted communication via SSL certificates and OAuth authentication via headers, APIs provide the highest levels of protection available in IT. A 2021 study by Salt Security on API security points out that more than 25 per cent of companies using APIs in production have no security strategy in place.

If more than 90 per cent of IT companies experienced security problems with APIs in 2020 (Gartner, 2021), it is because while it is true that the great potential of API integration has been clear to everyone from the outset, it is also true that due attention has not been paid to the issue of risks related to the exposure of data to third parties - which is ultimately the task of Application Programming Interfaces, or APIs.

API key and API tokens

API-driven architecture is based on the exposure of data and functions to third parties, so it is crucial to have a defence-aware strategy. Take the example of unintentional exposure of API keys, one of the most feared flaws for companies that routinely use APIs: all it takes is for a single developer to make the mistake of copying the API key into a forum or public repository, such as GitHub or Stack Overflow, to publicly expose their API key and allow any application to use it to query web services - obviously in the name and on behalf of the key holder.

API keys are alphanumeric codes that cannot exploit the control mechanisms typical of two-factor authentication, because they essentially consist of an opaque, encrypted string with no obvious meaning for the user. They can, however, be used, in the basic authentication phase, to generate an API token, i.e. a secure access credential that allows the user to interact - within well-defined functional and temporal limits - with the required web services.

In the OpenAPI marketplace, for example, the API key is generated at the moment of subscription to the service, and can be used to create API tokens via the OAuth authentication service, the standard network protocol most widely used to date to guarantee the security of interactions via API.

{ANCORA LEV=1}What is an API token?

But let's start from the beginning: an API token is an alphanumeric string found in the header of every API call that allows certain information about the user to be traced. When we speak of calls between RESTful APIs, in particular, the header of each request must be able to indicate

  • the authorisation token, or API token, in Bearer format;
  • the HTTP method, i.e. the specification of the type of request (e.g. delete).

If the API key is the basic level credential that allows access to any API marketplace, the API token is the actual 'entrance ticket', the one that allows one to formulate a valid header for an API request, i.e. to start interacting with third-party web applications.

The API token is a string in Bearer format, i.e. literally 'to the bearer': this means that it has no nominal value, but simply belongs to whoever is in possession of it. It goes without saying, given these premises, that whoever ends up in possession of the API token of a certain web service automatically becomes able to make requests in the name and on behalf of the application in question.

This is the main reason why the API token is often referred to as a kind of password, and the fundamental reason why it is recommended to be used as consciously as important access keys.

From Basic Authentication to OAuth

With the generation of an API token, one moves from basic authentication to OAuth authentication, which is perfectly consistent with a zero-trust architecture and reliable enough to allow access to remote server resources that are queried via API.

OAuth is an authentication standard that allows the use of resource access credentials to be delegated directly to apps, without involving the user and their personal credentials, such as an API key, in the process.

It is through the OAuth standard that bearer tokens are introduced instead of nominal credentials, such as API tokens or JSON Web Tokens (JWT), which allow web apps to 'present themselves' directly to the server and tell it that they have all the permissions to continue the interaction.

When data and functions are exposed via APIs, in fact, it is also defined who, how, when and with what limitations can access them. In order to send a request via API to the server, therefore, one must first prove that one has the necessary authorisations to forward the request. All this the server can verify from the token, without having any access to sensitive data such as the end user's credentials.

How API tokens work

API tokens, being 'bearer' tokens, require no further specification in order to be used. Once an API token is generated, it will automatically be inserted into the header of all API calls made through those credentials.

Each time a web service is queried, the server verifies the validity of the request precisely from the validity of the API token, which at this point represents a sort of 'signature' that is affixed to each call.

In addition to defining the starting point of the call, the API token identifies the boundaries of operation granted to the operator, who may, for instance, have decided upstream to use only certain HTTP methods or to be able to interact only with certain endpoints, or urls.

In addition to a signature, the API token is also a very detailed entry ticket - understandable only to the server and completely unreadable to the user - containing all the options available to the applicant.

When a client application wants to access protected resources on a certain server via the API, it signals via the token that it has received the necessary authorisations to proceed. But it is also required to signal all that it may intend to do using those credentials, and for how long.

Token API: the Time To Leave and scopes

In terms of security, the use of time-to-leave tokens significantly limits the risks of a token being compromised: as is easy to see, a token is vulnerable as long as it works.

Scopes, on the other hand, serve to define the paths one can take and the type of requests allowed within a web app interaction. There may be tokens authorised to use all functions (i.e. HTTP methods) available on particular endpoints, but there may also be tokens whose use is limited to precise methods (e.g. only GET and DELETE), but which may be valid on all endpoints.

In order to generate an API token on the OpenAPI marketplace, for example, it is sufficient to enter the email with which one subscribed to the service together with the API key associated with the account, and indicate precisely these two simple criteria, in the form of

  • duration of the token, i.e. the indication of the TTL (Time To Leave) associated with the access title - not exceeding 12 months on OpenAPI;
  • scopes, i.e. the HTTP + Endpoint method combinations expected to be used when querying the API.

Once the API token's deadline and scopes have been defined, clear boundaries are established that define and limit, at the same time, the credential's scope of operation and the surface it exposes to possible dangers.


Do you need to generate an API token?


All you need to know about API tokens

Share on: