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

# Authentication & API Keys

> Learn how to authenticate with the Minimo API using API keys

## Overview

The Minimo API uses **API keys** for authentication. All API requests must include a valid API key in the `Authorization` header using the Bearer token scheme.

## Creating an API Key

<Steps>
  <Step title="Navigate to API Key Section">
    Go to your [Minimo Account Settings](https://app.minimo.it/account) and select the **API Key** tab.
  </Step>

  {' '}

  <Step title="Create New API Key">Click the **"+ Create new API key"** button.</Step>

  {' '}

  <Step title="Configure Your Key">
    Provide the following information: - **Name**: A descriptive name to identify this key (e.g., "Production App",
    "Staging Environment") - **Permissions**: Select which API resources this key can access - **Expiration**: Set an
    expiration date (recommended: 1 year maximum)
  </Step>

  <Step title="Save and Copy">
    After creating the key, **copy it immediately** and store it securely. For security reasons, you won't be able to
    see the full key again.
  </Step>
</Steps>

<Warning>
  API keys are sensitive credentials. Treat them like passwords and never commit them to public repositories or share
  them publicly.
</Warning>

## Using Your API Key

Include your API key in the `Authorization` header of every request:

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

### Example Request (cURL)

```bash theme={null}
curl https://api.minimo.it/public/v1/contacts \
  -H "Authorization: Bearer mn-abc123-xyz789" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
  }'
```

### Example Request (JavaScript)

```javascript theme={null}
const response = await fetch('https://api.minimo.it/public/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mn-abc123-xyz789',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'customer@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
  }),
});

const data = await response.json();
console.log(data);
```

### Example Request (Python)

```python theme={null}
import requests

url = "https://api.minimo.it/public/v1/contacts"
headers = {
    "Authorization": "Bearer mn-abc123-xyz789",
    "Content-Type": "application/json"
}
payload = {
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

## API Key Format

Minimo API keys follow this format:

```
mn-{CLIENT_ID}-{SECRET_KEY}
```

**Example**: `mn-abc123-xyz789def456ghi789`

* `mn-` prefix identifies it as a Minimo key
* `CLIENT_ID` identifies your Minimo account
* `SECRET_KEY` is the secure token

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use Separate Keys for Different Environments">
    Create different API keys for development, staging, and production. This allows you to: - Rotate keys without
    affecting all environments - Track usage per environment - Revoke compromised keys without downtime
  </Accordion>

  {' '}

  <Accordion title="Set Appropriate Permissions">
    Grant each API key only the permissions it needs: - Read-only keys for analytics dashboards - Write-only keys for
    contact imports - Full access only when necessary
  </Accordion>

  {' '}

  <Accordion title="Rotate Keys Regularly">
    Set expiration dates and rotate your API keys at least annually. This limits the impact of leaked credentials.
  </Accordion>

  {' '}

  <Accordion title="Store Keys Securely">
    * Use environment variables in your application - Store in secure vaults (AWS Secrets Manager, HashiCorp Vault, etc.)
    * Never hardcode keys in your source code - Never commit keys to version control
  </Accordion>

  <Accordion title="Monitor Usage">
    Regularly review API key usage in your Minimo dashboard to detect: - Unusual request patterns - Unauthorized access
    attempts - Performance issues
  </Accordion>
</AccordionGroup>

## Authentication Errors

### 401 Unauthorized

**Cause**: Missing or invalid API key

**Response Example**:

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

**Solution**: Verify your API key is correct and included in the `Authorization` header.

### 403 Forbidden

**Cause**: API key lacks required permissions

**Response Example**:

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have permission to access this resource"
  }
}
```

**Solution**: Update the API key permissions in your Minimo dashboard or create a new key with appropriate access.

### 429 Too Many Requests

**Cause**: Rate limit exceeded

**Response Example**:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}
```

**Solution**: Implement exponential backoff and respect rate limits. Check the `X-RateLimit-*` headers in responses.

## Client-Side vs. Server-Side Usage

### Server-Side (Recommended) ✅

API keys should primarily be used in server-side applications where they can be kept secure:

* Backend APIs
* Server-side scripts
* Scheduled jobs/cron tasks
* Server-to-server integrations

### Client-Side (Use with Caution) ⚠️

While technically possible, using API keys client-side (browser, mobile apps) exposes them to users. If you must use keys client-side:

1. Create a **separate API key** with **read-only permissions**
2. Limit permissions to only what's needed (e.g., "Create Contact" only)
3. Set short expiration periods
4. Monitor usage closely

<Warning>
  For sensitive operations (sending messages, accessing analytics), always use server-side authentication.
</Warning>

## Revoking an API Key

If a key is compromised or no longer needed:

1. Go to [Account Settings](https://app.minimo.it/account) → **API Keys**
2. Find the key in the list
3. Click **Revoke** or **Delete**
4. Confirm the action

<Info>Revoked keys stop working immediately. Update your applications before revoking keys used in production.</Info>

## Need Help?

If you have questions about authentication or API key management:

* Email: [info@minimo.it](mailto:info@minimo.it)
* Dashboard: [app.minimo.it/account](https://app.minimo.it/account)