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.
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.
Request consent
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.Exchange the code
Send a form-encoded request. Set these variables from your application configuration and the validated callback: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:Handle OAuth errors
OAuth endpoint errors can returnerror 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.