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

# Authentication

> Learn how to authenticate your API requests

All requests to the Poelis Public API require authentication using a **REST API Key**. REST API keys are organization-scoped and provide access to all resources within your organization. New to the API? Start with the [Quick Start](/quickstart) to make your first request.

## Getting a REST API Key

1. Log in to the [Poelis web application ↗︎](https://app.poelis.com)
2. Navigate to [**Settings** ↗︎](https://app.poelis.com/settings) → [**Manage REST API Keys** ↗︎](https://app.poelis.com/settings/api-keys)
3. Click **Create REST API Key**
4. Give your key a descriptive name (e.g., "Production Integration", "CI/CD Pipeline")
5. Copy the key immediately - it won't be shown again!

<Warning>
  REST API keys are sensitive credentials. Store them securely and never commit them to version control.
</Warning>

## Using Your REST API Key

Include your REST API key in the `Authorization` header of every request using the Bearer token format:

```
Authorization: Bearer <poelis_api_YOUR_KEY_HERE>
```

### Example Request

```bash theme={null}
curl -X GET "https://api.poelis.com/v1/public/workspaces" \
  -H "Authorization: Bearer poelis_api_yyRCEbuLi8ugnBWNixCZQL4xKlLKBh-Gi_6zFf4CCIE" \
  -H "Content-Type: application/json"
```

## REST API Key Format

REST API keys follow this format:

* **Prefix**: `poelis_api_`
* **Length**: Variable (typically 40-60 characters)
* **Example**: `poelis_api_yyRCEbuLi8ugnBWNixCZQL4xKlLKBh-Gi_6zFf4CCIE`

## Key Scoping

REST API keys are **organization-scoped**, meaning:

* ✅ Access to all workspaces in your organization
* ✅ Access to all products, items, and properties within those workspaces
* ❌ No access to resources outside your organization
* ❌ No access to other organizations' data

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Store Securely" icon="lock">
    Use environment variables or secret management tools (e.g., AWS Secrets Manager, HashiCorp Vault)
  </Card>

  <Card title="Rotate Regularly" icon="refresh">
    Rotate your REST API keys periodically, especially if they may have been compromised
  </Card>

  <Card title="Use Different Keys" icon="key">
    Create separate keys for different usecases
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Review REST API key usage in your dashboard to detect unusual activity
  </Card>
</CardGroup>

## Key Management

### Creating Multiple Keys

You can create multiple REST API keys for different purposes:

* **Production**: For live integrations
* **CI/CD**: For automated pipelines
* **Monitoring**: For health checks and monitoring tools

### Revoking Keys

If a key is compromised or no longer needed:

1. Go to [**Settings** ↗︎](https://app.poelis.com/settings) → [**Manage REST API Keys** ↗︎](https://app.poelis.com/settings/api-keys)
2. Find the key you want to revoke
3. Click **Revoke**
4. The key will be immediately invalidated

<Warning>
  Revoking a key will immediately break all integrations using that key. Make sure to update your applications before revoking.
</Warning>

## Error Responses

If your REST API key is missing/invalid/revoked, the API returns **`401 Unauthorized`** with the standard error body format. See [Response Format](/api-reference/response-format) and [Status Codes](/api-reference/status-codes) for canonical examples.

## Next Steps

* Learn about [Rate Limiting](/guides/rate-limiting) to understand API usage limits
* Explore the [API Reference](/api-reference/introduction) to see all available endpoints
* Check out [Error Handling](/guides/error-handling) for proper error management