> ## 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.

# Authentication

> Learn how to authenticate with the Mavio API using API keys or OAuth 2.0.

## Bearer token authentication

All API requests require a valid API key passed in the `Authorization` header as a Bearer token.

```bash theme={null}
curl https://api.mavioapp.com/v1/meetings \
  -H "Authorization: Bearer mvo_live_abc123"
```

API keys are prefixed to help you identify them:

| Prefix      | Environment | Usage                              |
| ----------- | ----------- | ---------------------------------- |
| `mvo_live_` | Production  | Live data, production integrations |
| `mvo_test_` | Sandbox     | Test data, safe for development    |

<Warning>
  Never expose your API keys in client-side code, public repositories, or browser requests. Always make API calls from your server.
</Warning>

## Generating API keys

<Steps>
  <Step title="Open your dashboard">
    Navigate to [mavioapp.com/settings/api](https://mavioapp.com/settings/api) and sign in.
  </Step>

  <Step title="Create a new key">
    Click **Create API Key**, give it a descriptive name (e.g., "Slack integration"), and select the scopes you need.
  </Step>

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

You can create up to 25 API keys per account. Keys can be revoked at any time from the same settings page.

## Scopes

API keys can be scoped to limit access. When creating a key, select only the scopes your integration requires.

| Scope                | Description                                      |
| -------------------- | ------------------------------------------------ |
| `meetings:read`      | List and retrieve meetings                       |
| `meetings:write`     | Delete meetings                                  |
| `transcripts:read`   | Retrieve and search transcripts                  |
| `summaries:read`     | Retrieve summaries                               |
| `summaries:write`    | Regenerate summaries                             |
| `action_items:read`  | List action items                                |
| `action_items:write` | Update action item status, assignee, due date    |
| `webhooks:read`      | List webhook subscriptions                       |
| `webhooks:write`     | Create, update, and delete webhook subscriptions |

<Tip>
  Use the principle of least privilege. A read-only dashboard integration only needs `meetings:read`, `transcripts:read`, and `summaries:read`.
</Tip>

## OAuth 2.0

For applications that act on behalf of Mavio users (e.g., third-party integrations), use the OAuth 2.0 Authorization Code flow.

### 1. Register your application

Register your app at [mavioapp.com/settings/oauth-apps](https://mavioapp.com/settings/oauth-apps) to receive a `client_id` and `client_secret`.

### 2. Redirect the user to authorize

```
https://mavioapp.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=meetings:read transcripts:read&
  state=random_csrf_token
```

<ParamField query="client_id" type="string" required>
  Your OAuth application's client ID.
</ParamField>

<ParamField query="redirect_uri" type="string" required>
  The URL to redirect back to after authorization. Must match a registered redirect URI.
</ParamField>

<ParamField query="response_type" type="string" required>
  Must be `code`.
</ParamField>

<ParamField query="scope" type="string" required>
  Space-separated list of scopes to request.
</ParamField>

<ParamField query="state" type="string" required>
  A random string to prevent CSRF attacks. Verify this value when the user is redirected back.
</ParamField>

### 3. Exchange the authorization code for tokens

After the user authorizes your app, they are redirected to your `redirect_uri` with a `code` parameter. Exchange it for an access token:

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.mavioapp.com/v1/oauth/token \
    -H "Content-Type: application/json" \
    -d '{
      "grant_type": "authorization_code",
      "code": "AUTH_CODE_HERE",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "redirect_uri": "https://yourapp.com/callback"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "access_token": "mvo_oauth_abc123def456",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "mvo_refresh_xyz789",
    "scope": "meetings:read transcripts:read"
  }
  ```
</ResponseExample>

### 4. Refresh the access token

Access tokens expire after 1 hour. Use the refresh token to obtain a new one:

```bash theme={null}
curl -X POST https://api.mavioapp.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "mvo_refresh_xyz789",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
```

Refresh tokens are valid for 30 days and are single-use. Each refresh response includes a new refresh token.

## Security best practices

* Store API keys and tokens in environment variables or a secrets manager, never in source code.
* Rotate API keys periodically and immediately if you suspect a leak.
* Use scoped keys with the minimum permissions required.
* For OAuth, always validate the `state` parameter to prevent CSRF attacks.
* Monitor your API usage on the [dashboard](https://mavioapp.com/settings/api) for unexpected activity.