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

# Authentication

> Authenticate API requests using JWT Bearer tokens or API keys

# Authentication

NativeMessage supports two authentication methods: JWT Bearer tokens for user-based access and API keys for server-to-server integrations.

## JWT Bearer Token

JWT authentication provides short-lived access tokens with automatic refresh capabilities. Best for applications requiring user-level permissions.

### Login Flow

Obtain an access token by providing username and password:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "username": "your-username",
      "password": "your-password"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api-message.nativehub.live/api/v1/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'your-username',
      password: 'your-password'
    })
  });

  const { access_token, refresh_token } = await response.json();
  ```

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

  response = requests.post(
      'https://api-message.nativehub.live/api/v1/auth/login',
      json={
          'username': 'your-username',
          'password': 'your-password'
      }
  )

  data = response.json()
  access_token = data['access_token']
  refresh_token = data['refresh_token']
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900
}
```

### Using Access Tokens

Include the access token in the `Authorization` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api-message.nativehub.live/api/v1/messages \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api-message.nativehub.live/api/v1/messages', {
    headers: {
      'Authorization': `Bearer ${access_token}`
    }
  });
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api-message.nativehub.live/api/v1/messages',
      headers={'Authorization': f'Bearer {access_token}'}
  )
  ```
</CodeGroup>

### Token Refresh

Access tokens expire after 15 minutes. Use the refresh token to obtain a new access token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/auth/refresh \
    -H "Authorization: Bearer REFRESH_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api-message.nativehub.live/api/v1/auth/refresh', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${refresh_token}` }
  });

  const { access_token } = await response.json();
  ```

  ```python Python theme={null}
  response = requests.post(
      'https://api-message.nativehub.live/api/v1/auth/refresh',
      headers={'Authorization': f'Bearer {refresh_token}'}
  )

  access_token = response.json()['access_token']
  ```
</CodeGroup>

### Token Lifecycle

* **Access Token**: Valid for 15 minutes
* **Refresh Token**: Valid for 7 days
* Refresh tokens can be used multiple times until expiration

## API Key Authentication

API keys provide persistent authentication for server-to-server integrations without token management overhead.

### Creating an API Key

1. Log in to the NativeMessage dashboard
2. Navigate to Settings → API Keys
3. Click "Generate New Key"
4. Copy and securely store the key (shown only once)

### Using API Keys

Include the API key in the `X-API-Key` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api-message.nativehub.live/api/v1/messages \
    -H "X-API-Key: nmk_live_1234567890abcdef"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api-message.nativehub.live/api/v1/messages', {
    headers: {
      'X-API-Key': 'nmk_live_1234567890abcdef'
    }
  });
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api-message.nativehub.live/api/v1/messages',
      headers={'X-API-Key': 'nmk_live_1234567890abcdef'}
  )
  ```
</CodeGroup>

<Note>
  API keys inherit the permissions of the user who created them and remain valid until explicitly revoked.
</Note>

## Rate Limiting

All API requests are subject to rate limits of **200 requests per minute** per tenant.

### Rate Limit Headers

Each response includes rate limit information:

```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1676543210
```

* `X-RateLimit-Limit`: Maximum requests per minute
* `X-RateLimit-Remaining`: Remaining requests in current window
* `X-RateLimit-Reset`: Unix timestamp when the limit resets

<Warning>
  Exceeding rate limits returns a `429 Too Many Requests` response. Implement exponential backoff in your retry logic.
</Warning>

## Best Practices

<CardGroup cols={2}>
  <Card title="Secure Storage" icon="lock">
    Store tokens and API keys in environment variables or secure vaults, never in source code
  </Card>

  <Card title="Token Refresh" icon="rotate">
    Refresh JWT access tokens proactively before expiration to avoid interruptions
  </Card>

  <Card title="Server-to-Server" icon="server">
    Use API keys for automated systems and background processes
  </Card>

  <Card title="Key Rotation" icon="key">
    Rotate API keys periodically and revoke unused keys immediately
  </Card>
</CardGroup>