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

# Authentication

> Learn how to authenticate API requests securely

## Overview

To authenticate your API requests, you need an API key. This key identifies and authorizes your requests, ensuring only authorized users can access resources.

Your API key provides access to all data available to your account, including projects, site summaries, and monitoring data. ​

## Getting Your API Key

Follow these steps to obtain your API key:

<Steps>
  <Step title="Navigate to API Keys">
    Sign into the platform. In the bottom left, click on your name and select **API Keys**.

    <Frame>
      <img src="https://mintcdn.com/wellows/LA0e5Zk_k43SHwGv/images/api-keys/step1-api-keys.png?fit=max&auto=format&n=LA0e5Zk_k43SHwGv&q=85&s=1d7a067d36c45ebc1c417a681281f38f" alt="Navigate to API Keys" width="1910" height="914" data-path="images/api-keys/step1-api-keys.png" />
    </Frame>

    This will show your key generation portal and a table of your keys.

    <Frame>
      <img src="https://mintcdn.com/wellows/LA0e5Zk_k43SHwGv/images/api-keys/step1-api-key-2.png?fit=max&auto=format&n=LA0e5Zk_k43SHwGv&q=85&s=3008c9bfa91455211d26408f242815e9" alt="Navigate to APIeys" width="1910" height="914" data-path="images/api-keys/step1-api-key-2.png" />
    </Frame>
  </Step>

  <Step title="Configure your Key">
    Fill in the following fields to configure your API key:

    * **Key Name**: Enter a descriptive name for your API key (e.g., `example-api-key`)
    * **Key Level**: Choose the access scope for your key:
      * **User Level**: Access all your projects
      * **Project Level**: Access one specific project (requires selecting a project)

    <Frame caption="User Level - Access all projects">
      <img src="https://mintcdn.com/wellows/LA0e5Zk_k43SHwGv/images/api-keys/step2-configure-key-user.png?fit=max&auto=format&n=LA0e5Zk_k43SHwGv&q=85&s=864cceeac8a8cdfa0c3b58541522838a" alt="Configure API Key - User Level" width="1910" height="914" data-path="images/api-keys/step2-configure-key-user.png" />
    </Frame>

    If you select **Project Level**, an additional dropdown will appear to select the specific project:

    <Frame caption="Project Level - Access a specific project">
      <img src="https://mintcdn.com/wellows/LA0e5Zk_k43SHwGv/images/api-keys/step2-configure-key-project.png?fit=max&auto=format&n=LA0e5Zk_k43SHwGv&q=85&s=22af091e2e3c468eafa872037c14f4c5" alt="Configure API Key - Project Level" width="1910" height="914" data-path="images/api-keys/step2-configure-key-project.png" />
    </Frame>
  </Step>

  <Step title="Create your Key">
    When ready, click **Create API Key** to generate the key.

    <Frame>
      <img src="https://mintcdn.com/wellows/LA0e5Zk_k43SHwGv/images/api-keys/step3-create-apikey.png?fit=max&auto=format&n=LA0e5Zk_k43SHwGv&q=85&s=ff69d43e316c4edd4621eac4125c1663" alt="Create your Key" width="1910" height="914" data-path="images/api-keys/step3-create-apikey.png" />
    </Frame>
  </Step>

  <Step title="View API keys">
    <Check>
      That's it! You have now generated an API key that can be used to authenticate requests to the Wellows API.
    </Check>

    Your key will be displayed in a table along with other keys you generate. Return to this page at any time to see your keys, check expiry dates, or revoke an existing key.

    <Frame>
      <img src="https://mintcdn.com/wellows/LA0e5Zk_k43SHwGv/images/api-keys/step4-view-keys.png?fit=max&auto=format&n=LA0e5Zk_k43SHwGv&q=85&s=ee57ec1e6210dee01eb7325e83146a24" alt="View API keys" width="1910" height="914" data-path="images/api-keys/step4-view-keys.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  Your API key is sensitive information. Never share it publicly or commit it to version control. Store it securely and treat it like a password.
</Warning>

## Authentication Method

Include your API key in the `X-API-Key` header for all requests:

```bash theme={null}
curl -X GET "https://integrations.wellows.com/api/v1/validate" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"
```

## API Key Scope & Permissions

Your API key access level determines what data you can retrieve:

| Key Level         | Description                               | Project Header                                                            |
| ----------------- | ----------------------------------------- | ------------------------------------------------------------------------- |
| **User Level**    | Access all projects owned by your account | `X-Project-ID` required except for `/validate` and  `/projects` endpoints |
| **Project Level** | Scoped to a single project                | Not needed                                                                |

<Info>
  When using a **User Level** key, you must include the `X-Project-ID` header to specify which project you want to access except for `/validate` and  `/projects` endpoints
</Info>

## Security Best Practices

* **Keep keys private**: Never expose API keys in client-side code or public repositories
* **Use environment variables**: Store keys in environment variables or secure configuration files
* **Rotate regularly**: Consider rotating your API keys periodically for enhanced security
* **Monitor usage**: Check your API usage regularly to detect any unauthorized access

## Authentication Errors

Common authentication errors and their meanings:

| Status Code        | Error                    | Description                                                |
| ------------------ | ------------------------ | ---------------------------------------------------------- |
| `401 Unauthorized` | Invalid API key          | The provided API key is incorrect or expired               |
| `403 Forbidden`    | Insufficient permissions | Your API key doesn't have access to the requested resource |

## Need Help?

If you encounter authentication issues or need to request API access, contact our support team for assistance.