API key authentication

Your users can use Staart APIs (and your custom endpoints) using API key pairs. They can be generated under an organization using the endpoint PUT /organizations/:id/api-keys.

All endpoints that an organization or service exposes can be used with both authentication tokens (generated by logging in) and API keys. API keys use JSON Web Tokens (JWT) and we blacklist that JWT when you delete an API key. Using API keys also gives you an increased rate limit, which can be configured using environment variables.

The X-Api-Key header is used for API authentication. For example, requesting an organization’s details can be done as follows. This example uses the organization username hello:

fetch("https://example.com/organizations/hello", {
    headers: {
      "X-Api-Key": "Example API key"
    }
  })
  .then(response => response.json())
  .then(json => { /* organization details */ })
  .catch(error => console.log("Error", error))

An API key pair can have restrictions based on (i) IP address, (ii) referrer URLs, and (iii) APIs. By default, an API key pair has read-only organization permission and using just an API key without a secret key has no permissions, but increases your rate limit.