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

# Authentication

> Bearer token authentication for all API endpoints

All API requests require authentication via Bearer token in the Authorization header.

***

## Bearer Token Authentication

Every request to the Melonly API must include a valid Bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer your_api_token_here
```

Tokens are server-scoped and inherit the permissions of the user who created them.

<Warning>
  **Token Security:** API tokens provide full access to your server data. Store them securely and never expose them in client-side code or version control.
</Warning>

***

## Request Format

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -H "Authorization: Bearer your_api_token_here" \
      https://api.melonly.xyz/api/v1/server/info
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.melonly.xyz/api/v1/server/info', {
      headers: {
        'Authorization': 'Bearer your_api_token_here'
      }
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    headers = {
        'Authorization': 'Bearer your_api_token_here'
    }

    response = requests.get(
        'https://api.melonly.xyz/api/v1/server/info',
        headers=headers
    )
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    req, _ := http.NewRequest("GET", "https://api.melonly.xyz/api/v1/server/info", nil)
    req.Header.Set("Authorization", "Bearer your_api_token_here")

    client := &http.Client{}
    resp, err := client.Do(req)
    ```
  </Tab>
</Tabs>

***

## Token Context

When using your server token, there's no need to include server IDs in request paths. The API automatically infers server context from your token.

<CodeGroup>
  ```http Correct Usage theme={null}
  GET /api/v1/server/logs
  Authorization: Bearer your_server_token
  ```

  ```http Unnecessary (but valid) theme={null}
  GET /api/v1/server/12345/logs  
  Authorization: Bearer your_server_token
  ```
</CodeGroup>

All endpoints under `/server/*` automatically operate within your token's server scope.

***

## Rate Limiting

<Info>
  Rate limits are enforced per server token for premium users. Review the [rate limiting documentation](/rate-limits) for specific limits and best practices.
</Info>

Authentication failures and rate limit violations are tracked separately. Multiple authentication failures may result in temporary token suspension.

***

## Authentication Errors

Common authentication error responses:

<AccordionGroup>
  <Accordion title="401 Unauthorized - Missing Token">
    **Response:**

    ```json theme={null}
    {
      "error": "authorization header is required"
    }
    ```

    **Cause:** No `Authorization` header provided in the request.
  </Accordion>

  <Accordion title="401 Unauthorized - Invalid Token">
    **Response:**

    ```json theme={null}
    {
      "error": "invalid or expired token"
    }
    ```

    **Causes:**

    * Token has expired
    * Token was revoked or deleted
    * Malformed token string
    * Token doesn't exist
  </Accordion>

  <Accordion title="403 Forbidden - Insufficient Permissions">
    **Response:**

    ```json theme={null}
    {
      "error": "insufficient permissions for this operation"
    }
    ```

    **Cause:** Token lacks required permissions for the requested endpoint or operation.
  </Accordion>
</AccordionGroup>

***

## Token Management

<CardGroup cols={2}>
  <Card title="Generate Token" icon="plus" href="/quickstart">
    Create your first API token through the server dashboard
  </Card>

  <Card title="Security Best Practices" icon="shield" href="/security">
    Token rotation, storage, and security recommendations
  </Card>
</CardGroup>

<Tip>
  **Environment Variables:** Store your API tokens in environment variables rather than hardcoding them in your application source code.
</Tip>