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.

This mechanism applies only to Web Function endpoint invocations, that is, the HTTP POST requests described in the endpoint specification. It does not apply to event source URLs: browser EventSource clients cannot set custom headers, so event streams carry credentials differently. See the event specification for details.

Token lifecycle concerns—issuance, expiry, rotation, refresh, and revocation—are out of scope for this specification and are left to the discretion of the API developer.

Package endpoint flags

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 MUST result in a 400 Bad Request response, in accordance with the endpoint status code rules.

If the endpoint uses the error_triple flag, the ERROR_CODE to return is left to the discretion of the API developer. This specification RECOMMENDS, but does not require, the code UNAUTHORIZED for authentication-related failures.

Note that, as an exception to the case-sensitive string comparison used elsewhere in Web Function, clients that implement specific handling for this error MUST treat the error code as case-insensitive.

Finally, the capture_bearer flag can be specified on an endpoint to indicate that the endpoint will return a bearer token in its response. An endpoint with this flag MUST declare a returns of ["string"], and the returned string is the bearer token. This allows clients to automatically capture and store the token as part of the authentication flow.

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."
        }
      ]
    }
  ]
}