Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

HttpApiSecurity unstable

Defines security scheme declarations for declarative HTTP APIs.

Security schemes describe where credentials are read from and which credential type is passed to security middleware. They are consumed by HttpApiMiddleware.Service, HttpApiBuilder, generated clients, and OpenAPI generation, but they do not authenticate requests by themselves.

12 exports Since v4.0.0 Source

Annotations

annotate

unstable
Since v4.0.0

Adds an OpenAPI annotation value to a security scheme.

Signature

declare const annotate: {
  <I, S>(service: Key<I, S>, value: S): <A extends HttpApiSecurity>(self: A) => A;
  <A extends HttpApiSecurity, I, S>(self: A, service: Key<I, S>, value: S): A;
}

annotateMerge

unstable
Since v4.0.0

Merges OpenAPI annotations into a security scheme.

Signature

declare const annotateMerge: {
  <I>(annotations: Context<I>): <A extends HttpApiSecurity>(self: A) => A;
  <A extends HttpApiSecurity, I>(self: A, annotations: Context<I>): A;
}

Constructors

apiKey

unstable
Since v4.0.0

Creates an API key security scheme.

When to use

Use to require API key credentials passed through a header, query parameter, or cookie.

Details

Use HttpApiMiddleware.Service with a security option to implement API middleware for this security scheme.

Use HttpApiBuilder.securitySetCookie to set the correct cookie in a handler. By default, in is "header".

See

  • bearer for a Bearer token security scheme
  • basic for an HTTP Basic security scheme

Signature

declare function apiKey(options: {
  readonly in?: "query" | "header" | "cookie";
  readonly key: string;
}): ApiKey

basic

unstable
Since v4.0.0

Creates an HTTP Basic authentication security scheme.

When to use

Use to require HTTP Basic username/password credentials.

Details

Use HttpApiMiddleware.Service with a security option to implement API middleware for this security scheme.

See

  • bearer for a Bearer token security scheme
  • apiKey for an API-key security scheme

Signature

declare const basic: Basic

bearer

unstable
Since v4.0.0

Creates a Bearer token security scheme.

When to use

Use to require Authorization: Bearer ... credentials for an HTTP API group or endpoint.

Details

Use HttpApiMiddleware.Service with a security option to implement API middleware for this security scheme.

See

  • apiKey for an API-key security scheme
  • basic for an HTTP Basic security scheme

Signature

declare const bearer: Http

http

unstable
Since v4.0.0

Creates a Http token security scheme.

When to use

Use to require Authorization: scheme ... credentials for an HTTP API group or endpoint.

Details

Use HttpApiMiddleware.Service with a security option to implement API middleware for this security scheme.

See

  • apiKey for an API-key security scheme
  • basic for an HTTP Basic security scheme

Signature

declare function http(options: {
  readonly scheme: string;
}): Http

Models

ApiKey

interface unstable
Since v4.0.0

API key security scheme identifying the key name and whether it is read from a header, query parameter, or cookie.

Signature

interface ApiKey extends Proto<Redacted> {
  readonly _tag: "ApiKey";
  readonly in: "query" | "header" | "cookie";
  readonly key: string;
}

Basic

interface unstable
Since v4.0.0

HTTP Basic authentication security scheme whose decoded credential is Credentials.

Signature

interface Basic extends Proto<Credentials> {
  readonly _tag: "Basic";
}

Credentials

interface unstable
Since v4.0.0

Decoded credentials for HTTP Basic authentication.

Signature

interface Credentials {
  readonly password: Redacted;
  readonly username: string;
}

Http

interface unstable
Since v4.0.0

Http token security scheme whose decoded credential is a redacted token.

Signature

interface Http extends Proto<Redacted> {
  readonly _tag: "Http";
  readonly scheme: string;
}

HttpApiSecurity

type unstable
Since v4.0.0

Union of security schemes supported by the HTTP API OpenAPI model.

Signature

type HttpApiSecurity = Http | ApiKey | Basic

Other

HttpApiSecurity

unstable
Since v4.0.0

Helper types for HTTP API security schemes.