Authentication

Introduction

Bearer authentication is the security mechanism of choice for protecting Web Function endpoints, in which a user or system proves its identity by presenting a token. This token is passed in the HTTP Authorization header.

HTTP Authorization header

The HTTP Authorization header is the only supported mechanism for passing the bearer token in requests. The format is as follows:

Authorization: Bearer <token>

Here, <token> must be replaced with the actual bearer token. The format and method for obtaining the token are left to the discretion of the API developer and are not mandated by this specification. Tokens are typically opaque strings or JWTs (JSON Web Tokens), but the exact format depends on the implementation.

Package endpoint flag

The bearer_auth flag is used in the endpoint definitions as part of a package. This section is only relevant in the context of a package and can be disregarded if unused.

When the bearer_auth flag is present, the endpoint enforces authentication by validating the presence and validity of the token in the Authorization header. Unauthorized requests will typically result in a 400 Bad Request response.

If the endpoint uses the error_triple flag, the ERROR_CODE to return is at the discretion of the API developer. However, it is strongly recommended to use the error code UNAUTHORIZED for authentication-related failures.

Note that clients that implement specific handling for this error must treat the error code as case-insensitive.

Example Package Definition

The following section shows how to define a package endpoint which requires bearer authentication. See the code example below for implementation details.

{
  "base_url": "https://api.example.com",
  "name": "ExamplePackage",
  "flags": [],
  "docs": "This package defines endpoints for Example API.",
  "errors": [],
  "endpoints": [
    {
      "name": "find-user-by",
      "returns": ["object"],
      "group": "users",
      "flags": ["bearer_auth"],
      "docs": "Retrieves user data.",
      "errors": [],
      "arguments": [
        {
          "name": "id",
          "type": "string",
          "choices": [],
          "flags": ["required"],
          "docs": "Identifier of the user."
        }
      ]
    }
  ]
}