Authentication | Fern Documentation

Early access

The CLI generator is in early access. Reach out to get started.

Each generated CLI reads authentication credentials from the security schemes declared in your OpenAPI spec. Credentials can come from environment variables, CLI flags, files, or a combination of these through fallback chains.

Without a credential, the CLI still works — you can explore the command tree, view help, and use --dry-run.

Credential sources

The CLI supports several ways to supply credentials, configured at build time.

Source	Description
Environment variable	Read from an env var (the most common option).
CLI flag	Auto-registered as a `--<flag-name>` global flag.
File	Read trimmed contents from a file path (`~` is expanded).
Literal	Baked into the binary at compile time.
Fallback chain	Try multiple sources in order; first non-empty value wins.

A typical fallback chain lets the CLI flag override the env var, which in turn overrides a file:

$ # CLI flag takes priority
$ box users get-current-user --api-token sk-123
$ 
$ # Otherwise falls back to the environment variable
$ export BOX_API_KEY=sk-123
$ box users get-current-user
$ 
$ # Otherwise reads from a file
$ echo "sk-123" > ~/.box/token
$ box users get-current-user

Supported auth schemes

The CLI supports every scheme type that OpenAPI’s securitySchemes defines:

Scheme	How the CLI applies it
Bearer (`http: bearer`)	Sends `Authorization: Bearer <token>`.
API key (`apiKey`)	Sends the key in the configured header (for example, `X-Auth-Token`).
Basic (`http: basic`)	Sends `Authorization: Basic <base64(user:pass)>`. Each field has its own credential source.
OAuth 2	Treated as bearer — sends `Authorization: Bearer <token>`.

Auth strategies

When a spec declares multiple security schemes, the CLI composes them according to one of these strategies:

Strategy	Behavior
Auto	Default. Infers the right composition from the spec’s `security` blocks.
Any	The API accepts any one of the declared schemes. The first scheme with a credential wins.
All	The API requires every scheme simultaneously (for example, HMAC signature plus API key).
Routing	Per-operation dispatch. Each endpoint’s `security` block determines which schemes to use.

Operations that declare security: [] (an empty list) opt out of authentication entirely — no credentials are sent regardless of what’s configured.

Configure the `any` strategy

When an API accepts more than one credential under the any strategy, the CLI authenticates with whichever source is populated, using the first scheme that has a credential. Declaring the schemes requires two steps:

In your OpenAPI spec, define the schemes under securitySchemes and list them as multiple auth schemes in the security array.

openapi.yml

1 components:
2   securitySchemes:
3     # ...BearerAuth and TokenAuth defined here
4 security:
5   - BearerAuth: []
6   - TokenAuth: []

In generators.yml, define the same schemes under auth-schemes and compose them with api.auth set to any.

generators.yml

1 auth-schemes:
2   # ...BearerAuth and TokenAuth defined here, each with its env var
3 api:
4   auth:
5     any: [BearerAuth, TokenAuth]

The scheme names must match across both files.

A scheme that’s missing from the spec is silently ignored, even when its environment variable is set. With both declared, set either variable and the command runs:

$ # Authenticate with MY_API_KEY
$ export MY_API_KEY=sk-123
$ my-cli users list
$ 
$ # Or authenticate with MY_TOKEN instead
$ export MY_TOKEN=tok-456
$ my-cli users list

Help output

Every generated CLI includes a dynamically rendered Authentication: section in its --help output listing every scheme, the expected env var or flag, and whether a credential is detected.