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

# Authentication

> Learn how to authenticate your API requests to AlloMia

AlloMia API requires authentication for all requests to ensure data security and appropriate access control. We support two levels of API keys to meet different integration needs: tenant-level and organization-level keys.

## Bearer Authentication

AlloMia uses Bearer token authentication for all API requests. Include your API key in the `Authorization` header using the following format:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Types of API Keys

AlloMia offers two types of API keys, each with different scopes and use cases:

### 1. Tenant-Level API Keys

Tenant-level API keys have the highest level of access and can manage resources across all organizations within a tenant.

**Use cases:**

* Platform-wide integrations
* Multi-organization management
* Administrative tools and automation

**How to obtain:**
Tenant-level API keys are provisioned by the AlloMia team. Contact your account representative to request one.

### 2. Organization-Level API Keys

Organization-level API keys provide access limited to a specific organization's resources. These are self-service keys that you can generate directly from the AlloMia dashboard.

**Use cases:**

* Organization-specific integrations
* Department-level applications
* Individual service connections

## Generating Organization-Level API Keys

You can create up to 5 organization-level API keys through the AlloMia dashboard:

1. Navigate to **Settings** > **API Keys** in your AlloMia dashboard
2. Click the **Add Key** button
3. Enter a descriptive name for your API key (e.g., "Production Integration")
4. Click **Create API Key**
5. **Important:** Copy your API key immediately and store it securely. The complete key will only be displayed once.

<img className="block mt-6 mb-6 border rounded-lg" src="https://mintlify.s3.us-west-1.amazonaws.com/allomia-dcfc501a/images/api-key-creation.png" alt="API Key Creation Interface" width="600" />

## Revoking API Keys

To revoke an organization-level API key:

1. Go to **Settings** > **API Keys** in your dashboard
2. Locate the key you want to revoke
3. Click the delete (trash) icon
4. Confirm the deletion

Once deleted, any services using the key will immediately lose access to the API.

## Security Best Practices

API keys provide direct access to your data. Follow these security best practices:

* **Never expose your API key** in client-side code, public repositories, or any public-facing assets
* Store API keys in secure environment variables or a secrets management service
* Use different API keys for different environments (development, staging, production)
* Implement proper key rotation procedures
* Use HTTPS for all API requests
* Implement proper error handling to avoid leaking sensitive information
* Consider using organization-level keys over tenant-level keys when possible to limit scope

## Error Responses

If authentication fails, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
```

## Example Request with Authentication

```bash theme={null}
curl -X POST https://allomia.com/api/organization \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Valley Health Clinic",
    "email": "info@valleyhealthclinic.com",
    "address": "123 Main Street",
    "city": "San Francisco",
    "stateProvince": "CA",
    "postalCode": "94105",
    "country": "USA",
    "phoneNumber": "+14155551234",
    "timezone": "America/Los_Angeles"
  }'
```