# Authentication

Secure your API calls with proper authentication. This guide explains how to authenticate your requests to the MugglePay API.

## Overview

All API calls to MugglePay require authentication using an API token. Keep your API token secure and never expose it in client-side code.

## API Token Authentication

### Getting Your API Token

1. Log in to the [Merchant Portal](https://merchants.mugglepay.com/)
2. Navigate to the API section
3. Copy your unique API token

### Using Your API Token

Include your API token in the `token` header of all authenticated requests:

```http
HTTP Header: 
token: YOUR_API_TOKEN_HERE
```

## Request Requirements

### Content-Type Header

All POST requests must include the `Content-Type: application/json` header:

```http
Content-Type: application/json
```

### Required vs Optional Fields

* **Required fields** are marked with "Yes" in the API documentation
* **Optional fields** can be omitted if not needed
* Fields marked with (\*) are required

## Rate Limits

### Free Plan Limits

1. **Create Order API: 500 requests per hour per user ID**
   * This limit applies to the `createOrder` (POST) API for merchants
   * If you reach the limit, wait for the timer to reset in an hour
2. **General API: 10,000 requests per hour per IP address**
   * This applies to all APIs regardless of authentication requirements
   * Includes GetOrder, CreateOrder, Checkout, and other APIs

### Increasing Limits

To increase your rate limits:

1. Create a ticket in the [Help Center](https://merchants.mugglepay.com/help/ticketcreate)
2. Contact customer service through the chat widget
3. Provide details about your expected usage

## Security Best Practices

### ✅ Do's

* Store your API token securely on your server
* Use HTTPS for all API calls
* Rotate your API token periodically
* Monitor your API usage for unusual activity

### ❌ Don'ts

* Never expose your API token in client-side code
* Don't commit API tokens to version control
* Avoid sharing API tokens between different applications
* Don't use the same token for development and production

## Code Examples

### cURL Example

```bash
curl -X POST \
  https://api.mugglepay.com/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'token: YOUR_API_TOKEN_HERE' \
  -d '{
    "merchant_order_id": "order_123",
    "price_amount": 10.00,
    "price_currency": "USD"
  }'
```

### JavaScript Example

```javascript
const response = await fetch('https://api.mugglepay.com/v1/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'token': 'YOUR_API_TOKEN_HERE'
  },
  body: JSON.stringify({
    merchant_order_id: 'order_123',
    price_amount: 10.00,
    price_currency: 'USD'
  })
});
```

### Python Example

```python
import requests

headers = {
    'Content-Type': 'application/json',
    'token': 'YOUR_API_TOKEN_HERE'
}

data = {
    'merchant_order_id': 'order_123',
    'price_amount': 10.00,
    'price_currency': 'USD'
}

response = requests.post(
    'https://api.mugglepay.com/v1/orders',
    headers=headers,
    json=data
)
```

## Common Authentication Errors

| Error Code            | Description                  | Solution                                                        |
| --------------------- | ---------------------------- | --------------------------------------------------------------- |
| `UNAUTHORIZED`        | Invalid or missing API token | Check your API token and ensure it's included in the header     |
| `TOKEN_EXPIRED`       | API token has expired        | Generate a new API token in the Merchant Portal                 |
| `RATE_LIMIT_EXCEEDED` | Too many requests            | Wait for rate limit reset or contact support to increase limits |

## Related Documentation

* [Create Order API](https://github.com/MugglePay/MugglePay/blob/master/API/basic/order/CreateOrder.md) - Learn how to use authentication with order creation
* [Error Codes](/basic/errorcodes.md) - Complete list of API error codes
* [Getting Started](https://github.com/MugglePay/MugglePay/blob/master/API/basic/faq/GetStarted.md) - Step-by-step integration guide

## Next Steps

1. **Test your authentication** by making a simple API call
2. **Review the** [**Create Order API**](https://github.com/MugglePay/MugglePay/blob/master/API/basic/order/CreateOrder.md) to see authentication in action
3. **Set up error handling** for authentication failures
4. **Monitor your API usage** to stay within rate limits


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mugglepay.com/basic/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.