Authentication

All commands that communicate with the Prefect API (blocks deploy, deployments deploy, deployments run) accept a shared set of connection options.

The --api-url flag (or the PREFECT_API_URL environment variable) is always required. The URL must end with /api.

No authentication

For a Prefect server that does not require authentication:

prefector blocks deploy \
  --api-url "http://prefect.internal/api" \
  --blocks-dir path/to/specs

Or via environment variable:

export PREFECT_API_URL="http://prefect.internal/api"
prefector blocks deploy --blocks-dir path/to/specs

Basic auth (--api-auth-string)

For a Prefect server protected by HTTP basic authentication, pass the base64-encoded user:password string (or any value accepted by PREFECT_API_AUTH_STRING):

prefector blocks deploy \
  --api-url "https://prefect.example.com/api" \
  --api-auth-string "$PREFECT_API_AUTH_STRING" \
  --blocks-dir path/to/specs

Can also be set via environment variable:

export PREFECT_API_AUTH_STRING="..."

Keycloak — operator (username/password)

For interactive or CI logins where a user account's credentials are available:

prefector blocks deploy \
  --api-url "https://prefect.example.com/api" \
  --keycloak-token-url "https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token" \
  --keycloak-username "$KEYCLOAK_USER" \
  --keycloak-password "$KEYCLOAK_PASSWORD" \
  --blocks-dir path/to/specs

Both --keycloak-username and --keycloak-password must be provided together. The client ID for the direct-grant flow defaults to prefect-cli; override with --keycloak-direct-grant-client-id if needed.

Keycloak — application (client credentials)

For CI pipelines or service accounts using OAuth2 client credentials:

prefector blocks deploy \
  --api-url "https://prefect.example.com/api" \
  --keycloak-token-url "https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token" \
  --keycloak-client-id "$KEYCLOAK_CLIENT_ID" \
  --keycloak-client-secret "$KEYCLOAK_CLIENT_SECRET" \
  --blocks-dir path/to/specs

Both --keycloak-client-id and --keycloak-client-secret must be provided together.

SSL certificates

For servers with a self-signed or private CA certificate, provide the certificate file:

prefector blocks deploy \
  --api-url "https://prefect.internal/api" \
  --ssl-cert /etc/ssl/certs/my-ca.crt \
  --blocks-dir path/to/specs

Or via environment variable:

export SSL_CERT_FILE=/etc/ssl/certs/my-ca.crt

The certificate is used for all HTTPS connections, including Keycloak token requests.

Auth modes are mutually exclusive

Only one auth method may be used per command invocation. Passing options from more than one group (e.g. --api-auth-string together with --keycloak-username) is an error.

Reference

Option	Env var	Description
--api-url	PREFECT_API_URL	Prefect API URL. Must end with /api.
--ssl-cert	SSL_CERT_FILE	Path to a CA certificate file for HTTPS.
--api-auth-string	PREFECT_API_AUTH_STRING	HTTP basic auth credential string.
--keycloak-token-url	—	Keycloak token endpoint URL. Required when using any Keycloak auth.
--keycloak-username	—	Keycloak username (use with --keycloak-password).
--keycloak-password	—	Keycloak password (use with --keycloak-username).
--keycloak-direct-grant-client-id	—	Keycloak client ID for direct-grant login. Default: prefect-cli.
--keycloak-client-id	—	Keycloak OAuth2 client ID (use with --keycloak-client-secret).
--keycloak-client-secret	—	Keycloak OAuth2 client secret (use with --keycloak-client-id).