> ## Documentation Index
> Fetch the complete documentation index at: https://help.gowindmill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> Connect an application with authorization code, PKCE, and workspace-scoped tokens.

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](https://api.gowindmill.com/.well-known/oauth-authorization-server), including these endpoints outside `/api/v2`:

| Purpose | Endpoint |
| - | - |
| Dynamic registration | `POST https://api.gowindmill.com/oauth/register` |
| Authorization | `GET https://api.gowindmill.com/oauth/authorize` |
| Code exchange and refresh | `POST https://api.gowindmill.com/oauth/token` |
| Revocation | `POST https://api.gowindmill.com/oauth/revoke` |

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.

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST 'https://api.gowindmill.com/oauth/register' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_name":"Example employee reporting",
    "redirect_uris":["https://example.test/oauth/callback"],
    "grant_types":["authorization_code","refresh_token"],
    "response_types":["code"],
    "token_endpoint_auth_method":"none"
  }'
```

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.

## 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.

For example, the authorization URL has this shape. URL-encode each query parameter value:

```text theme={null}
https://api.gowindmill.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_ENCODED_REDIRECT_URI&code_challenge=YOUR_CHALLENGE&code_challenge_method=S256&scope=offline_access&state=YOUR_STATE
```

## Exchange the code

Send a form-encoded request. Set these variables from your application configuration and the validated callback:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST 'https://api.gowindmill.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "client_id=$WINDMILL_CLIENT_ID" \
  --data-urlencode "code=$WINDMILL_AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=$WINDMILL_REDIRECT_URI" \
  --data-urlencode "code_verifier=$WINDMILL_CODE_VERIFIER"
```

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](https://help.gowindmill.com/api-reference/employees/search-employee-profiles.md) 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](https://help.gowindmill.com/api-reference/making-requests.md).

## Refresh or revoke tokens

Refresh by sending the latest refresh token to the same token endpoint:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST 'https://api.gowindmill.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "client_id=$WINDMILL_CLIENT_ID" \
  --data-urlencode "refresh_token=$WINDMILL_REFRESH_TOKEN"
```

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:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request POST 'https://api.gowindmill.com/oauth/revoke' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "client_id=$WINDMILL_CLIENT_ID" \
  --data-urlencode "token=$WINDMILL_REFRESH_TOKEN" \
  --data-urlencode 'token_type_hint=refresh_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](https://help.gowindmill.com/api-reference/errors.md).

API v2 requests made with OAuth tokens share the [500/minute budget per OAuth client and workspace](https://help.gowindmill.com/api-reference/rate-limits.md), across that client's users and tokens in the workspace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.