Endpoints can have dedicated security-related inputs. The type of those inputs is captured as the first type parameter, A, of the Endpoint type. Security inputs can be added by .securityIn methods, and behave the same as regular inputs.

The security inputs play a crucial role when defining the server logic for an endpoint. They also aim to clearly communicate which part of the endpoint’s input is security-related. Finally, they are part of a mechanism for building reusable base “secure” endpoints, either with the security logic provided or not, which can later be extended by other endpoints.

Authentication inputs

Inputs which map to authentication credentials can be created using methods available in the auth object. Such inputs in addition to the base input (such as an Authorization header or a cookie), contain security-related metadata, for example the name of the security scheme that should be used for documentation.


Note that security inputs added using .securityIn can contain both dedicated auth credentials inputs created using one of the methods from auth, and arbitrary “regular” inputs, such as path components. Similarly, regular inputs can contain inputs created through auth, though typically this shouldn’t be the case.

Currently, the following authentication inputs are available (assuming import sttp.tapir._):

  • auth.apiKey(anotherInput): wraps any other input and designates it as an api key. The input is typically a header, cookie or a query parameter

  • auth.basic[T]: reads data from the Authorization header, removing the Basic prefix. To parse the data as a base64-encoded username/password combination, use: basic[UsernamePassword].

  • auth.bearer[T]: reads data from the Authorization header, removing the Bearer prefix. To get the string as a token, use: bearer[String].

  • auth.oauth2.authorizationCode(authorizationUrl, tokenUrl, scopes, refreshUrl): EndpointInput[String]: creates an OAuth2 authorization using authorization code - sign in using an auth service (for documentation, requires defining also the oauth2-redirect.html, see Generating OpenAPI documentation)

Multiple authentication inputs indicate that all of the given authentication values should be provided. Specifying alternative authentication methods (where only one value out of many needs to be provided) is currently not supported. However, optional authentication can be described by mapping to optional types, e.g. bearer[Option[String]].

Authentication challenges

For each auth scheme, one can define WWW-Authenticate headers that should be returned by the server in case input is not provided. Default behavior is to return 401 status with the headers needed for authentication. To return different status codes when authentication is missing, the decode failure handler can be customised.

For example, if you define endpoint.get.securityIn("path").securityIn(auth.basic[UsernamePassword]()) then the browser will show you a password prompt.


Read on about streaming support.