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

# API Keys

> Create and manage API keys for programmatic access to the Mavio platform.

API keys let you authenticate programmatic requests to the Mavio API. Use them to build custom integrations, automate workflows, and connect Mavio data with your own tools and systems.

## Creating an API key

<Steps>
  <Step title="Open developer settings">
    Navigate to **Settings > Developer > API Keys**.
  </Step>

  <Step title="Click Create Key">
    Click **Create API Key** and provide:

    * **Name** — a descriptive label (e.g., "CRM Sync", "Analytics Pipeline")
    * **Scopes** — the permissions this key should have (see scopes below)
    * **Expiration** — optional expiration date (recommended for security)
  </Step>

  <Step title="Copy the key">
    Your API key is displayed once. Copy it immediately and store it securely. You cannot retrieve the full key again after closing this dialog.
  </Step>

  <Step title="Start using the key">
    Include the key in your API requests using the `Authorization` header:

    ```
    Authorization: Bearer mavio_sk_your_api_key_here
    ```
  </Step>
</Steps>

<Warning>
  Treat API keys like passwords. Never commit them to source control, expose them in client-side code, or share them in plain text. Use environment variables or a secrets manager.
</Warning>

## Key scopes

Each API key can be restricted to specific scopes, limiting what the key can access:

| Scope                | Access                                                 |
| -------------------- | ------------------------------------------------------ |
| `meetings:read`      | List and retrieve meetings, transcripts, and summaries |
| `meetings:write`     | Create, update, and delete meetings                    |
| `recordings:read`    | Download recording audio files                         |
| `transcripts:read`   | Retrieve transcript content                            |
| `transcripts:write`  | Edit transcript content and speaker labels             |
| `notes:read`         | Read meeting notes and minutes                         |
| `notes:write`        | Create and edit notes and minutes                      |
| `action-items:read`  | List action items                                      |
| `action-items:write` | Create, update, and complete action items              |
| `channels:read`      | List channels and their meetings                       |
| `channels:write`     | Create channels, add meetings, manage members          |
| `speakers:read`      | List speaker profiles                                  |
| `speakers:write`     | Create and manage speaker profiles                     |
| `team:read`          | Read team membership and settings                      |
| `webhooks:manage`    | Create and manage webhook endpoints                    |

<Tip>
  Follow the principle of least privilege. Grant only the scopes your integration actually needs. You can always create a new key with broader permissions later.
</Tip>

## Rate limits

API requests are rate-limited based on your plan:

| Plan           | Rate limit                |
| -------------- | ------------------------- |
| **Free**       | 60 requests per minute    |
| **Pro**        | 300 requests per minute   |
| **Team**       | 1,000 requests per minute |
| **Enterprise** | Custom (contact sales)    |

Rate limit headers are included in every API response:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1713100800
```

When the rate limit is exceeded, the API returns a `429 Too Many Requests` response. Retry after the time indicated in the `X-RateLimit-Reset` header.

## Managing keys

### Viewing existing keys

Go to **Settings > Developer > API Keys** to see all active keys. The list shows:

* Key name and partial key value (last 4 characters)
* Scopes assigned
* Creation date and expiration date
* Last used timestamp

### Rotating keys

To rotate a key without downtime:

1. Create a new key with the same scopes.
2. Update your integration to use the new key.
3. Verify the integration works with the new key.
4. Revoke the old key.

### Revoking keys

Click the three-dot menu on any key and select **Revoke**. The key stops working immediately. This action cannot be undone.

## Usage monitoring

Track how each API key is being used from **Settings > Developer > API Keys > \[Key] > Usage**:

* **Request count** — total API calls over time
* **Endpoint breakdown** — which API endpoints are called most
* **Error rate** — percentage of requests returning errors
* **Last used** — the most recent successful request

## Security best practices

<AccordionGroup>
  <Accordion title="Use environment variables">
    Store API keys in environment variables (`MAVIO_API_KEY`) rather than hardcoding them. All major hosting platforms and CI/CD systems support environment variable management.
  </Accordion>

  <Accordion title="Set expiration dates">
    Always set an expiration date on API keys. Rotate keys on a regular schedule (e.g., every 90 days) to limit the blast radius of a compromised key.
  </Accordion>

  <Accordion title="Use separate keys per integration">
    Create a dedicated API key for each integration or service. This lets you revoke access for one integration without affecting others.
  </Accordion>

  <Accordion title="Monitor for unusual activity">
    Review API key usage regularly. Unexpected spikes in request volume or requests to unusual endpoints may indicate a compromised key.
  </Accordion>

  <Accordion title="Restrict by IP address (Enterprise)">
    Enterprise plans support IP allowlists for API keys. Restrict each key to the IP addresses of the servers that use it.
  </Accordion>
</AccordionGroup>