Skip to main content
Use OAuth when users authorize an application to access their Windmill workspace. Windmill supports the authorization code flow with PKCE using S256, plus refresh tokens. Client credentials and implicit grants aren’t supported.

Register your application

Windmill publishes OAuth server metadata, including these endpoints outside /api/v2: Dynamic registration creates a public client with token_endpoint_auth_method: "none". Use an HTTPS redirect URI for your application; loopback redirects for local applications use HTTP. Redirect URIs can’t contain fragments. Non-loopback redirects must exactly match a registered URI. Loopback matching permits a different port while retaining the scheme, host, path, and query.
Use a redirect URI that your application controls in place of the synthetic example. Save the returned client_id and securely store registration_access_token. The registration token isn’t an API bearer credential. Register once for your application rather than once per user connection. Registration has a separate limit of 10 requests per hour per IP address. If you already have a confidential client, include its client_secret in code-exchange, refresh, and revocation request bodies. Keep that secret on your server. Dynamic registration doesn’t issue a confidential client secret.
1

Create PKCE and state values

Generate a fresh random PKCE verifier and compute its SHA-256 hash, encoded as base64url without padding, for code_challenge. Generate an unpredictable state, and store both values securely for this authorization attempt. Use an OAuth library to manage these values and the callback.
2

Send the user to authorization

Redirect the user’s browser to /oauth/authorize with response_type=code, client_id, the registered redirect_uri, code_challenge, code_challenge_method=S256, and state. Request scope=offline_access if you need a refresh token. An empty scope requests no refresh token; offline_access is the supported optional scope. Don’t request openid or invent endpoint-specific scopes.
3

Let the user select a workspace

Windmill’s consent page handles sign-in and workspace selection. The user authorizes one eligible workspace. API access uses that user’s current permissions within the selected workspace; OAuth doesn’t grant additional workspace roles or resource access.
4

Validate the callback

On approval, Windmill redirects to your registered URI with code and the supplied state. Verify that state matches the stored value before exchanging the code. Handle error=access_denied if the user declines. Codes expire after 10 minutes and can be used only once.
For example, the authorization URL has this shape. URL-encode each query parameter value:

Exchange the code

Send a form-encoded request. Set these variables from your application configuration and the validated callback:
The response includes access_token, token_type: "Bearer", expires_in in seconds, and scope. It includes refresh_token when offline_access was granted. Use the returned expires_in to schedule refresh instead of assuming a fixed access-token lifetime. Send Authorization: Bearer <access_token> on employee searches and other API v2 calls. Use the company ID or slug of the workspace the user selected. The token can’t access another company, even if the user belongs to both. See Making requests.

Refresh or revoke tokens

Refresh by sending the latest refresh token to the same token endpoint:
Store the returned access and refresh tokens securely and replace the previous values. Refresh rotates the refresh token. OAuth sessions currently have no fixed session expiration, but tokens can be revoked and workspace access can change. If refresh fails, reconnect through consent rather than retrying indefinitely. When disconnecting your integration, revoke its token:
Revoking an access or refresh token revokes the associated session. An unknown token can return success; a client-authentication failure can still return an error. Discard locally stored tokens when disconnecting.

Handle OAuth errors

OAuth endpoint errors can return error as a string and error_description as diagnostic text, for example {"error":"invalid_scope","error_description":"Unknown scopes requested: example"}. Handle callback errors before expecting a code. These responses differ from the API v2 application error envelope. API v2 requests made with OAuth tokens share the 500/minute budget per OAuth client and workspace, across that client’s users and tokens in the workspace.