All endpoints require authentication. In order to do it, always provide a X-Api-Key: {api_key} header on every request.

Managing API keys

API keys are generated (and managed) from the command line. Run the api-key:generate command to get a new and valid API key.

This command optionally accepts an expiration date through the --expirationDate|-e modifier:

shlink api-key:generate -e 2020-01-01

Disabling existing API keys is also possible, through the api-key:disable command:

shlink api-key:disable 1ae89449-f8d2-4b44-baf7-dd7eb0b05017

Both disabled and expired API keys will be considered invalid by Shlink, rejecting any request done with them.


Starting with Shlink v2.5.0, API keys can have a set of roles that will limit the operations they can do. Read the docs to learn how.

Errors during authentication

When performing an API call, if no API key is provided or it is invalid/disabled/expired, the server will return this response payload, with status 401.

  "type": "",
  "detail": "Provided API key does not exist or is invalid",
  "title": "Invalid API key",
  "status": 401