API Documentation

Authentication

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

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

Previous to shlink v1.13.0, it was also possible to call to the special /rest/authenticate endpoint, which expects an API key to be provided and returns a token which expires in a week.

You had to pass it on every request in the Authorization: Bearer [token] header, and every response returned the Authorization header as well, with a refreshed token which will last another week.

This authentication method will keep working, but it is considered deprecated.

Errors during authentication

When using the X-Api-Key mechanism, if no API key is provided or it is invalid, the server will return this, with status 401.

        {
    "error": "INVALID_API_KEY",
    "message": "Provided API key does not exist or is invalid"
}
    

When using the Authorization mechanism, if a token is not provided or the token has expired, the server will return an error like this, with a status 401:

        {
    "error": "INVALID_AUTH_TOKEN",
    "message": "Missing or invalid auth token provided. Perform a new authentication request and send provided token on every new request on the \"Authorization\" header"
}
    

If the token was properly provided in the Authorization header but the authorization type is missing or has any value different than Bearer, the server will return one of these errors, with status 401.

        {
    "error": "INVALID_AUTHORIZATION",
    "message": "You need to provide the Bearer type in the Authorization header."
}
    
        {
    "error": "INVALID_AUTHORIZATION",
    "message": "Provided authorization type <type> is not supported. Use Bearer instead."
}
    

All the tokens generated by Shlink's REST API follow the JSON Web Token standard. You can read about it at jwt.io.