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

# Authentication

> Authenticate with the Matter API using personal access tokens.

Every request to the Matter API must include a valid API token. Tokens are scoped to your account and give full read/write access to your library.

## Getting your token

1. Open [Matter settings](https://web.getmatter.com/settings)
2. Click **Generate API Token**
3. Copy the token

Your token looks like this:

```
mat_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8
```

The `mat_` prefix identifies it as a Matter API token. If you ever see one in logs or code, you know what it is.

## Using your token

Pass the token in the `Authorization` header on every request:

```bash theme={null}
curl https://api.getmatter.com/public/v1/me \
  -H "Authorization: Bearer mat_your_token_here"
```

<Warning>
  **Never share your token or commit it to source control.** Treat it like a password. Use environment variables or a secrets manager.
</Warning>

## Token lifecycle

| Action         | What happens                                                    |
| -------------- | --------------------------------------------------------------- |
| **Generate**   | Creates a new token. Any previous token is immediately revoked. |
| **Regenerate** | Invalidates the old token and issues a new one.                 |
| **Revoke**     | Destroys the token. API access stops immediately.               |

You can have **one active token** at a time. Generating a new token automatically revokes the previous one.

## Security best practices

<AccordionGroup>
  <Accordion title="Store tokens in environment variables">
    ```bash theme={null}
    export MATTER_API_TOKEN="mat_your_token_here"

    curl https://api.getmatter.com/public/v1/me \
      -H "Authorization: Bearer $MATTER_API_TOKEN"
    ```
  </Accordion>

  <Accordion title="Use .env files for local development">
    ```bash theme={null}
    # .env (add to .gitignore!)
    MATTER_API_TOKEN=mat_your_token_here
    ```
  </Accordion>

  <Accordion title="Rotate tokens periodically">
    If you suspect a token has been exposed, regenerate it immediately in your [settings](https://web.getmatter.com/settings).
  </Accordion>
</AccordionGroup>

## Error responses

If authentication fails, the API returns `401 Unauthorized`:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API token."
  }
}
```

If your account doesn't have an active Pro subscription:

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "The Matter API requires an active Pro subscription."
  }
}
```