Authentication Configuration

The serverpod_swagger generator can add OpenAPI security schemes to your API specification via CLI flags. This page explains how to configure authentication for your generated documentation.

Setting an Auth Type

Use the --auth flag to define a security scheme. When an auth type is set, all endpoints are secured by default.

dart run serverpod_swagger:generate --auth=jwt

Supported auth types:

Value	OpenAPI Scheme
`jwt`	HTTP Bearer with JWT format
`apikey`	API Key in header (`X-API-Key`)
`basic`	HTTP Basic authentication
`oauth2`	OAuth 2.0 implicit flow

Custom Auth Description

You can provide a custom description for the security scheme:

dart run serverpod_swagger:generate --auth=jwt --auth-description="Provide your JWT token from the /login endpoint"

Controlling Which Endpoints Are Secured

By default, when --auth is provided, all endpoints are secured. You can control this with the following flags:

Secure specific endpoints only

When --secure-endpoints is provided, only the listed endpoints are secured. Everything else is left unsecured.

dart run serverpod_swagger:generate --auth=jwt --secure-endpoints=admin,user/deleteAccount

You can specify an entire endpoint class (e.g., admin) or a specific method (e.g., user/deleteAccount).

Unsecure specific endpoints

When --unsecure-endpoints is provided, those endpoints are explicitly left open while the rest follow the default policy.

dart run serverpod_swagger:generate --auth=jwt --unsecure-endpoints=auth/login,auth/register

Single URL overrides

For fine-grained control, you can secure or unsecure a single path:

dart run serverpod_swagger:generate --auth=jwt \
  --secure-single-url=/admin/dashboard \
  --unsecure-single-url=/status/health

Disabling Auth Globally

To remove all security definitions from every endpoint:

dart run serverpod_swagger:generate --unauth

The --disable-auth flag is an alias for --unauth.

Updating Auth on an Existing Spec

Use --update to modify security settings on an existing apispec.jsonwithout regenerating the entire spec from source:

dart run serverpod_swagger:generate --update --auth=apikey --unsecure-endpoints=public

Testing Authentication in Swagger UI

Once your spec includes a security scheme, the Swagger UI will show an "Authorize" button. Click it, enter your credentials, and test authenticated endpoints directly from the browser.

Documentation