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

# Authentication

> How to authenticate your API requests and manage API keys

All Mufi API requests are authenticated using **Bearer tokens**. Your API key acts as a JWT-signed token that identifies your project and permission level.

## Getting Your API Key

<Steps>
  <Step title="Sign in to the Mufi Dashboard">
    Go to [my.mufi.app](https://my.mufi.app) and authenticate with your email via magic link.
  </Step>

  <Step title="Select or create a project">
    Each project has its own users, events, products, and API keys.
  </Step>

  <Step title="Generate an API key">
    Navigate to the API Keys section and generate a new key. You'll receive a JWT token to use in your API requests.
  </Step>
</Steps>

<Info>
  Don't have an account? Email [connect@mufi.app](mailto:connect@mufi.app) to request access.
</Info>

## Using Your API Key

Include your API key as a Bearer token in the `Authorization` header of every request:

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer $MUFI_API_KEY" \
    https://api.mufi.app/v1/version
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.mufi.app/v1/version', {
    headers: { 'Authorization': `Bearer ${process.env.MUFI_API_KEY}` }
  });
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.get('https://api.mufi.app/v1/version', headers={
      'Authorization': f'Bearer {os.getenv("MUFI_API_KEY")}'
  })
  ```
</CodeGroup>

## Permission Levels

Each API key has one of two permission levels:

| Permission | What it allows                                                             |
| ---------- | -------------------------------------------------------------------------- |
| **Write**  | Full access — create and modify users, events, products, and all resources |
| **Read**   | Query-only — fetch users, list events, check balances, view products       |

Calling a write-only endpoint with a read-only key returns `403 Forbidden`.

## Key Management

| Behavior          | Detail                                                                                          |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| **Expiration**    | API keys do not expire automatically — they remain valid until revoked                          |
| **Regeneration**  | You can regenerate a key at any time from the Dashboard. The old key is immediately invalidated |
| **Multiple keys** | Generate separate keys for different environments (staging, production) or services             |

## Security Checklist

<Check>Store API keys in environment variables, never in source code</Check>
<Check>Use keys only on the server side — never expose them in frontend code</Check>
<Check>Use read-only keys when you only need to query data</Check>
<Check>Regenerate keys immediately if you suspect they've been compromised</Check>
<Check>Use separate keys for staging and production environments</Check>

<Warning>
  If your API key is compromised, regenerate it immediately from the [Mufi Dashboard](https://my.mufi.app) or email [connect@mufi.app](mailto:connect@mufi.app) for emergency revocation.
</Warning>