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

# Authentication

> Create an API key with the access your integration needs and send it securely.

Authenticate API requests with an API key or an [OAuth access token](https://help.gowindmill.com/api-reference/oauth.md). Both act with the authenticated user's current permissions in one workspace.

## Create an API key

Workspace members can create their own keys. Managing other members' keys requires separate workspace permission.

**1. Open API key settings**

In the Windmill Dashboard, open [**Settings → API keys**](https://app.gowindmill.com/COMPANY/config/api-keys). The browser route is `/s/{company}/config/api-keys`.

**2. Choose access and expiration**

Select **Create API key** and enter a descriptive name, such as `Employee reporting`. Choose **Read** for searches and other read operations, or **Read/write** when your integration needs to change data. Choose an expiration, then select **Create**. The dialog initially selects **Read/write** and **90 days**; select **Read** explicitly for the getting-started example.

**3. Store the key**

Copy the plaintext key into a secret manager. Windmill shows the full key only once. Keys start with `wm_api_`. If you lose the value, create a replacement and revoke the old key.

## Send the bearer header

Use this header on every API-key request:

```http theme={null}
Authorization: Bearer <key>
```

In a shell, load the key from secure storage into `WINDMILL_API_KEY`, then use:

```bash theme={null}
--header "Authorization: Bearer $WINDMILL_API_KEY"
```

Keep credentials on your server. Don't embed keys in browser code, commit them to source control, or include them in shell history, support messages, screenshots, or request logs.

## Understand permissions

A key inherits its creator's **current** workspace permissions and is further limited by its selected access mode. A read/write key doesn't grant employee-management permissions that its creator lacks. Resource visibility and access rules still apply.

**Read** keys can call read operations such as [Search employee profiles](https://help.gowindmill.com/api-reference/employees/search-employee-profiles.md), even though that operation uses `POST`. They can't call mutations such as [Update an employee profile](https://help.gowindmill.com/api-reference/employees/update-an-employee-profile.md).

A key belongs to the workspace where you created it. Changing the company ID in the URL doesn't authorize access to another workspace, even if you belong to both.

### Resolve authentication failures

* **401:** check the `Bearer` header, the full key value, and whether the key is expired or revoked. Replace an invalid key.
* **403:** check that the key belongs to the requested workspace, its access mode permits the operation, and its creator still has the required workspace and resource permissions.

See [Errors](https://help.gowindmill.com/api-reference/errors.md) for request IDs and other status codes.

## Rotate or revoke a key

To rotate, create a new key, update your integration's secret, and confirm a read request succeeds. Then revoke the old key from **Settings → API keys** using its **Revoke** action. Revocation prevents further use of that key. Revoke exposed or unused keys promptly.

You can manage your own keys. Members with permission to manage all workspace keys can also manage other members' keys. For applications that need user consent and refreshable credentials, follow [OAuth](https://help.gowindmill.com/api-reference/oauth.md).


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