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

# Authentication

> Secure your API requests with proper authentication

## API Key Authentication

All Refine API endpoints require authentication using an API key. Include your API key in the request headers:

```bash theme={null}
REFINE_API_KEY: your_api_key_here
```

<Warning>
  Keep your API key secure and never expose it in client-side code or public repositories.
</Warning>

## API Key Types

Refine API keys come with different permission levels:

<AccordionGroup>
  <Accordion title="ADMIN" icon="user-shield">
    Full access to resources within your organization. Can manage catalogs, products, and access all API endpoints for your organization.
  </Accordion>

  <Accordion title="USER" icon="user">
    Read access to resources within your organization. Can search products and get recommendations but cannot modify catalogs or products.
  </Accordion>
</AccordionGroup>

## Authorization Rules

Different endpoints have different authorization requirements. All access is limited to resources within your organization:

| Endpoint Type      | ADMIN | USER |
| ------------------ | ----- | ---- |
| Catalog Management | ✓     | ✗    |
| Product Management | ✓     | ✗    |
| Search             | ✓     | ✓    |
| Recommendations    | ✓     | ✓    |

<Note>
  All API keys can only access resources within their own organization. You cannot access another organization's catalogs or products.
</Note>

## Error Responses

Authentication failures will return appropriate HTTP status codes:

### 401 Unauthorized

Returned when:

* `REFINE_API_KEY` header is missing
* API key is invalid
* Organization is inactive
* Rate limit grace period has expired

```json theme={null}
{
  "status": 401,
  "message": "Unauthorized",
  "time": "2024-06-14T19:21:00Z",
  "method": "GET",
  "url": "/organizations/a8cd2722-1234-4567-9abc-def123456789/catalogs"
}
```

### 403 Forbidden

Returned when:

* API key doesn't have permission for the requested resource
* Attempting to access resources from a different organization

```json theme={null}
{
  "status": 403,
  "message": "Forbidden",
  "time": "2024-06-14T19:21:00Z",
  "method": "POST",
  "url": "/organizations/a8cd2722-1234-4567-9abc-def123456789/catalogs"
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Rotate Keys Regularly" icon="rotate">
    Rotate your API keys periodically to maintain security
  </Card>

  <Card title="Use Environment Variables" icon="lock">
    Store API keys in environment variables, not in code
  </Card>

  <Card title="Restrict Key Permissions" icon="shield">
    Use the minimum permission level required for your use case
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Track API key usage to detect any unusual activity
  </Card>
</CardGroup>