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

# Auth API

> User authentication, authorization, and API key management

# Auth Service API

The Auth Service handles user authentication, role-based access control (RBAC), and API key management. It provides secure JWT-based authentication and granular permission management for multi-tenant applications.

<Info>
  **Base URL:** `https://paymentgateway.redahaloubi.com/api/v1`

  All endpoints are prefixed with `/api/v1`
</Info>

***

## Authentication Methods

The Auth Service supports multiple authentication methods depending on the use case:

<Tabs>
  <Tab title="JWT Tokens">
    **Use Case:** Dashboard, merchant portals, web applications

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

    **Token Lifecycle:**

    * **Access Token:** 24 hours
    * **Refresh Token:** 7 days
    * **Algorithm:** HS256 (HMAC-SHA256)

    **Obtain tokens via:** `/auth/login` endpoint
  </Tab>
</Tabs>

***

## Rate Limits

<CardGroup cols={2}>
  <Card title="Login Endpoint" icon="shield">
    **5 requests per minute** per IP address

    After 5 failed login attempts, account is locked for 30 minutes
  </Card>

  <Card title="Register Endpoint" icon="user-plus">
    **7 requests per hour** per IP address

    Prevents spam account creation
  </Card>

  <Card title="Other Endpoints" icon="gauge">
    **100 requests per second** per user

    Standard rate limit for authenticated endpoints
  </Card>

  <Card title="API Key Endpoints" icon="key">
    **50 requests per second** per merchant

    Used for payment processing
  </Card>
</CardGroup>

***

## Authentication Endpoints

### Register User

<ParamField path="POST" type="endpoint">
  `/auth/register`
</ParamField>

Create a new user account. Email verification is required before full access.

**Request Body**

<ParamField body="name" type="string" required>
  Full name of the user

  **Min length:** 2 characters
</ParamField>

<ParamField body="email" type="string" required>
  Valid email address

  **Format:** Standard email validation

  **Unique:** Must not be already registered
</ParamField>

<ParamField body="password" type="string" required>
  Secure password

  **Min length:** 8 characters

  **Security:** Hashed with bcrypt (cost 10)
</ParamField>

**Example Request**

```bash theme={null}
curl -X POST https://paymentgateway.redahaloubi.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Merchant",
    "email": "john@yourstore.com",
    "password": "SecurePass123!"
  }'
```

**Response (201 Created)**

```json theme={null}
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "John Merchant",
      "email": "john@yourstore.com",
      "email_verified": false,
      "status": "pending_verification",
      "created_at": "2026-01-24T10:00:00Z"
    }
  },
  "message": "Registration successful. Please verify your email."
}
```

<Accordion title="Error Responses">
  **400 Bad Request - Email Already Exists**

  ```json theme={null}
  {
    "success": false,
    "error": "email already registered"
  }
  ```

  **400 Bad Request - Weak Password**

  ```json theme={null}
  {
    "success": false,
    "error": "password must be at least 8 characters"
  }
  ```

  **400 Bad Request - Invalid Email**

  ```json theme={null}
  {
    "success": false,
    "error": "invalid email format"
  }
  ```

  **429 Too Many Requests**

  ```json theme={null}
  {
    "success": false,
    "error": "rate limit exceeded. try again in 3600 seconds"
  }
  ```
</Accordion>

***

### Login

<ParamField path="POST" type="endpoint">
  `/auth/login`
</ParamField>

Authenticate user and receive JWT access and refresh tokens.

**Request Body**

<ParamField body="email" type="string" required>
  Registered email address
</ParamField>

<ParamField body="password" type="string" required>
  User's password
</ParamField>

**Example Request**

```bash theme={null}
curl -X POST https://paymentgateway.redahaloubi.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@yourstore.com",
    "password": "SecurePass123!"
  }'
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "John Merchant",
      "email": "john@yourstore.com",
      "email_verified": false,
      "status": "active"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJleHAiOjE3MDU4NTcxMDB9.xXx_xXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJ0eXBlIjoicmVmcmVzaCIsImV4cCI6MTcwNjI5MzEwMH0.yYy_yYyYyYyYyYyYyYyYyYyYyYyYyYyYyYyYyYyYyYy",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}
```

<Accordion title="Error Responses">
  **401 Unauthorized - Invalid Credentials**

  ```json theme={null}
  {
    "success": false,
    "error": "invalid email or password"
  }
  ```

  **401 Unauthorized - Account Locked**

  ```json theme={null}
  {
    "success": false,
    "error": "account locked due to too many failed login attempts. try again in 30 minutes"
  }
  ```

  **401 Unauthorized - Account Suspended**

  ```json theme={null}
  {
    "success": false,
    "error": "account suspended. please contact support"
  }
  ```

  **429 Too Many Requests**

  ```json theme={null}
  {
    "success": false,
    "error": "too many login attempts. try again in 60 seconds"
  }
  ```
</Accordion>

<Warning>
  **Account Lockout Policy:**

  * After **5 failed login attempts**, the account is locked for **30 minutes**
  * Failed attempts are tracked per email address
  * Lockout is automatic and cannot be manually bypassed
</Warning>

***

### Refresh Token

<ParamField path="POST" type="endpoint">
  `/auth/refresh`
</ParamField>

Get a new access token using a refresh token. Use this to maintain user sessions without requiring re-login.

**Request Body**

<ParamField body="refresh_token" type="string" required>
  Valid refresh token from login response
</ParamField>

**Example Request**

```bash theme={null}
curl -X POST https://paymentgateway.redahaloubi.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.NEW_ACCESS_TOKEN...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.NEW_REFRESH_TOKEN...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}
```

<Accordion title="Error Responses">
  **401 Unauthorized - Invalid Refresh Token**

  ```json theme={null}
  {
    "success": false,
    "error": "invalid or expired refresh token"
  }
  ```

  **401 Unauthorized - Token Revoked**

  ```json theme={null}
  {
    "success": false,
    "error": "refresh token has been revoked"
  }
  ```
</Accordion>

<Info>
  **Token Rotation:** Each refresh returns a new access token **and** a new refresh token. The old refresh token is invalidated.
</Info>

***

### Get Profile

<ParamField path="GET" type="endpoint">
  `/auth/profile`
</ParamField>

Get the authenticated user's profile information.

**Authentication Required:** JWT Bearer Token

**Example Request**

```shellscript theme={null}
curl -X GET https://paymentgateway.redahaloubi.com/api/v1/auth/profile \
  -H "Authorization: Bearer {access_token}"
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "John Merchant",
      "email": "john@yourstore.com",
      "email_verified": false,
      "status": "active",
      "created_at": "2026-01-24T10:00:00Z",
      "last_login_at": "2026-01-24T15:30:00Z",
      "last_login_ip": "192.168.1.100"
    }
  }
}
```

<Accordion title="Error Responses">
  **401 Unauthorized - Missing Token**

  ```json theme={null}
  {
    "success": false,
    "error": "authorization header required"
  }
  ```

  **401 Unauthorized - Invalid Token**

  ```json theme={null}
  {
    "success": false,
    "error": "invalid or expired access token"
  }
  ```
</Accordion>

***

### Logout

<ParamField path="POST" type="endpoint">
  `/auth/logout`
</ParamField>

Revoke the current session and invalidate the access token.

**Authentication Required:** JWT Bearer Token

**Example Request**

```bash theme={null}
curl -X POST https://paymentgateway.redahaloubi.com/api/v1/auth/logout \
  -H "Authorization: Bearer {access_token}"
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "message": "logged out successfully"
}
```

<Info>
  **Single Device Logout:** This only logs out the current session. To logout from all devices, use the "Logout All" endpoint (coming soon).
</Info>

***

### Change Password

<ParamField path="POST" type="endpoint">
  `/auth/change-password`
</ParamField>

Change the user's password. This action logs out all sessions and requires re-login.

**Authentication Required:** JWT Bearer Token

**Request Body**

<ParamField body="old_password" type="string" required>
  Current password for verification
</ParamField>

<ParamField body="new_password" type="string" required>
  New password (min 8 characters)
</ParamField>

**Example Request**

```bash theme={null}
curl -X POST https://paymentgateway.redahaloubi.com/api/v1/auth/change-password \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "SecurePass123!",
    "new_password": "NewSecurePass456!"
  }'
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "message": "password changed successfully. please login again"
}
```

<Accordion title="Error Responses">
  **400 Bad Request - Incorrect Old Password**

  ```json theme={null}
  {
    "success": false,
    "error": "old password is incorrect"
  }
  ```

  **400 Bad Request - Weak Password**

  ```json theme={null}
  {
    "success": false,
    "error": "new password must be at least 8 characters"
  }
  ```

  **400 Bad Request - Same Password**

  ```json theme={null}
  {
    "success": false,
    "error": "new password must be different from old password"
  }
  ```
</Accordion>

<Warning>
  **Security Notice:** Changing password will revoke **all active sessions** on all devices. User must login again with the new password.
</Warning>

***

### Get Sessions

<ParamField path="GET" type="endpoint">
  `/auth/sessions`
</ParamField>

List all active sessions for the authenticated user across all devices.

**Authentication Required:** JWT Bearer Token

**Example Request**

```bash theme={null}
curl -X GET https://paymentgateway.redahaloubi.com/api/v1/auth/sessions \
  -H "Authorization: Bearer {access_token}"
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "session_abc123def456",
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        "created_at": "2026-01-24T10:00:00Z",
        "expires_at": "2026-01-25T10:00:00Z",
        "is_current": true
      },
      {
        "id": "session_xyz789uvw012",
        "ip_address": "10.0.1.50",
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)",
        "created_at": "2026-01-23T14:30:00Z",
        "expires_at": "2026-01-24T14:30:00Z",
        "is_current": false
      }
    ]
  }
}
```

<Info>
  **Session Management:** The `is_current` flag indicates the session making this request. All sessions expire automatically after 24 hours.
</Info>

***

## Role & Permission Endpoints

### Get All Roles

<ParamField path="GET" type="endpoint">
  `/roles`
</ParamField>

Get a list of all available roles in the system.

**Authentication Required:** JWT Bearer Token

**Example Request**

```bash theme={null}
curl -X GET https://paymentgateway.redahaloubi.com/api/v1/roles \
  -H "Authorization: Bearer {access_token}"
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "data": {
    "roles": [
      {
        "id": "role_owner_123",
        "name": "Owner",
        "description": "Merchant owner - full access to all features"
      },
      {
        "id": "role_admin_456",
        "name": "Admin",
        "description": "Full access to payments, invoices, team, and settings"
      },
      {
        "id": "role_manager_789",
        "name": "Manager",
        "description": "Can manage payments and invoices"
      },
      {
        "id": "role_staff_012",
        "name": "Staff",
        "description": "Can only view and create transactions"
      }
    ]
  }
}
```

### Role Hierarchy

<Steps>
  <Step title="Owner">
    **Full Control**

    * All permissions
    * Cannot be removed
    * Automatically assigned on merchant creation
    * Can manage team and assign roles
  </Step>

  <Step title="Admin">
    **Administrative Access**

    * Manage payments, invoices, reports
    * Manage team members (except owner)
    * Configure settings and webhooks
    * Cannot delete merchant
  </Step>

  <Step title="Manager">
    **Operational Access**

    * Create and manage payments
    * Issue refunds
    * View reports
    * Cannot manage team or settings
  </Step>

  <Step title="Staff">
    **Limited Access**

    * View transactions
    * Create payments
    * No refund capability
    * Read-only access to reports
  </Step>
</Steps>

***

### Get Role Details

<ParamField path="GET" type="endpoint">
  `/roles/:id`
</ParamField>

Get detailed information about a specific role including all its permissions.

**Authentication Required:** JWT Bearer Token

**Path Parameters**

<ParamField path="id" type="string" required>
  Role ID (e.g., `role_admin_456`)
</ParamField>

**Example Request**

```bash theme={null}
curl -X GET https://paymentgateway.redahaloubi.com/api/v1/roles/role_admin_456 \
  -H "Authorization: Bearer {access_token}"
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "data": {
    "role": {
      "id": "role_admin_456",
      "name": "Admin",
      "description": "Full access to payments, invoices, team, and settings",
      "permissions": [
        {
          "id": "perm_transactions_read",
          "resource": "transactions",
          "action": "read",
          "description": "View transaction details"
        },
        {
          "id": "perm_transactions_create",
          "resource": "transactions",
          "action": "create",
          "description": "Create new transactions"
        },
        {
          "id": "perm_transactions_refund",
          "resource": "transactions",
          "action": "refund",
          "description": "Issue refunds"
        },
        {
          "id": "perm_team_manage",
          "resource": "team",
          "action": "manage",
          "description": "Manage team members"
        },
        {
          "id": "perm_settings_update",
          "resource": "settings",
          "action": "update",
          "description": "Update merchant settings"
        }
      ]
    }
  }
}
```

### Permission Format

All permissions follow the `resource:action` format:

<CardGroup cols={2}>
  <Card title="Resources" icon="folder">
    * `transactions`
    * `invoices`
    * `team`
    * `settings`
    * `reports`
    * `api_keys`
  </Card>

  <Card title="Actions" icon="bolt">
    * `read` - View data
    * `create` - Create new records
    * `update` - Modify existing records
    * `delete` - Remove records
    * `manage` - Full CRUD access
  </Card>
</CardGroup>

***

### Assign Role to User

<ParamField path="POST" type="endpoint">
  `/roles/assign`
</ParamField>

Assign a role to a user for a specific merchant. Users can have different roles across different merchants.

**Authentication Required:** JWT Bearer Token

**Required Permission:** `team:manage` in the target merchant

**Request Body**

<ParamField body="user_id" type="string" required>
  ID of the user receiving the role
</ParamField>

<ParamField body="role_id" type="string" required>
  ID of the role to assign
</ParamField>

<ParamField body="merchant_id" type="string" required>
  ID of the merchant context
</ParamField>

**Example Request**

```bash theme={null}
curl -X POST https://paymentgateway.redahaloubi.com/api/v1/roles/assign \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_abc123",
    "role_id": "role_manager_789",
    "merchant_id": "merchant_xyz456"
  }'
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "message": "role assigned successfully",
  "data": {
    "user_id": "user_abc123",
    "role_id": "role_manager_789",
    "merchant_id": "merchant_xyz456",
    "assigned_at": "2026-01-24T10:00:00Z",
    "assigned_by": "user_def789"
  }
}
```

<Accordion title="Error Responses">
  **403 Forbidden - Insufficient Permissions**

  ```json theme={null}
  {
    "success": false,
    "error": "you do not have permission to manage team members"
  }
  ```

  **404 Not Found - User Not Found**

  ```json theme={null}
  {
    "success": false,
    "error": "user not found"
  }
  ```

  **409 Conflict - Role Already Assigned**

  ```json theme={null}
  {
    "success": false,
    "error": "user already has this role in this merchant"
  }
  ```
</Accordion>

***

### Remove Role from User

<ParamField path="DELETE" type="endpoint">
  `/roles/assign`
</ParamField>

Remove a role assignment from a user in a specific merchant.

**Authentication Required:** JWT Bearer Token

**Required Permission:** `team:manage` in the target merchant

**Request Body**

<ParamField body="user_id" type="string" required>
  ID of the user
</ParamField>

<ParamField body="role_id" type="string" required>
  ID of the role to remove
</ParamField>

<ParamField body="merchant_id" type="string" required>
  ID of the merchant context
</ParamField>

**Example Request**

```bash theme={null}
curl -X DELETE https://paymentgateway.redahaloubi.com/api/v1/roles/assign \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_abc123",
    "role_id": "role_manager_789",
    "merchant_id": "merchant_xyz456"
  }'
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "message": "role removed successfully"
}
```

<Warning>
  **Cannot Remove Owner:** The Owner role cannot be removed. Transfer ownership to another user before attempting removal.
</Warning>

***

### Get User Roles

<ParamField path="GET" type="endpoint">
  `/roles/user/:user_id/merchant/:merchant_id`
</ParamField>

Get all roles assigned to a user in a specific merchant.

**Authentication Required:** JWT Bearer Token

**Path Parameters**

<ParamField path="user_id" type="string" required>
  User ID
</ParamField>

<ParamField path="merchant_id" type="string" required>
  Merchant ID
</ParamField>

**Example Request**

```bash theme={null}
curl -X GET https://paymentgateway.redahaloubi.com/api/v1/roles/user/user_abc123/merchant/merchant_xyz456 \
  -H "Authorization: Bearer {access_token}"
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "data": {
    "roles": [
      {
        "id": "role_admin_456",
        "name": "Admin",
        "description": "Full access to payments, invoices, team, and settings",
        "assigned_at": "2026-01-20T14:00:00Z"
      }
    ]
  }
}
```

***

### Get User Permissions

<ParamField path="GET" type="endpoint">
  `/roles/user/:user_id/merchant/:merchant_id/permissions`
</ParamField>

Get all effective permissions for a user in a specific merchant (aggregated from all assigned roles).

**Authentication Required:** JWT Bearer Token

**Path Parameters**

<ParamField path="user_id" type="string" required>
  User ID
</ParamField>

<ParamField path="merchant_id" type="string" required>
  Merchant ID
</ParamField>

**Example Request**

```bash theme={null}
curl -X GET https://paymentgateway.redahaloubi.com/api/v1/roles/user/user_abc123/merchant/merchant_xyz456/permissions \
  -H "Authorization: Bearer {access_token}"
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "data": {
    "permissions": [
      {
        "resource": "transactions",
        "action": "read"
      },
      {
        "resource": "transactions",
        "action": "create"
      },
      {
        "resource": "transactions",
        "action": "refund"
      },
      {
        "resource": "invoices",
        "action": "read"
      },
      {
        "resource": "team",
        "action": "manage"
      },
      {
        "resource": "settings",
        "action": "update"
      }
    ]
  }
}
```

<Info>
  **Permission Caching:** Permissions are cached in Redis for 10 minutes for fast validation. Changes to roles take effect within 10 minutes.
</Info>

***

## Security Best Practices

<AccordionGroup>
  <Accordion title="Password Security" icon="lock">
    **Requirements:**

    * Minimum 8 characters
    * Use a mix of uppercase, lowercase, numbers, and symbols
    * Avoid common passwords and dictionary words

    **Storage:**

    * Passwords are hashed with bcrypt (cost factor 10)
    * Original passwords are never stored or logged
    * Cannot be retrieved, only reset
  </Accordion>

  <Accordion title="Token Management" icon="key">
    **Access Tokens:**

    * 24-hour expiry
    * Stored hashed in database (SHA-256)
    * Automatically revoked on password change

    **Refresh Tokens:**

    * 7-day expiry
    * Single-use (rotated on each refresh)
    * Revoked on logout

    **Best Practices:**

    * Store tokens securely (e.g., httpOnly cookies, secure storage)
    * Never expose tokens in URLs or logs
    * Implement token refresh before expiry
  </Accordion>

  <Accordion title="API Key Security" icon="shield">
    **Generation:**

    * Cryptographically secure random generation
    * 64 characters of entropy
    * SHA-256 hashed in database

    **Usage:**

    * Use different keys for production and testing
    * Rotate keys every 90 days
    * Never commit keys to version control
    * Use environment variables or secrets managers

    **Monitoring:**

    * Track last\_used\_at for each key
    * Alert on unusual usage patterns
    * Deactivate unused keys
  </Accordion>

  <Accordion title="Session Management" icon="clock">
    **Session Tracking:**

    * IP address and user agent logged
    * Session duration: 24 hours
    * Concurrent sessions allowed

    **Session Invalidation:**

    * Logout: Current session only
    * Password change: All sessions
    * Manual revocation: Specific session

    **Redis Storage:**

    * Sessions cached for fast validation
    * TTL matches token expiry
    * Automatic cleanup on expiry
  </Accordion>

  <Accordion title="Account Protection" icon="user-shield">
    **Failed Login Protection:**

    * 5 attempts = 30-minute lockout
    * Tracked per email address
    * Automatic unlock after timeout

    **Rate Limiting:**

    * Login: 5 requests/minute per IP
    * Register: 3 requests/hour per IP
    * API calls: 100 requests/second per user

    **Suspicious Activity:**

    * Login from new IP/device logs event
    * Multiple failed attempts trigger alert
    * Account suspension for security violations
  </Accordion>
</AccordionGroup>

***

## Error Reference

Common error codes and their meanings:

<ResponseField name="400" type="Bad Request">
  Invalid request format, missing required fields, or validation errors

  **Common causes:**

  * Missing required fields
  * Invalid email format
  * Password too short
  * Invalid UUID format
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Authentication failed or token invalid

  **Common causes:**

  * Missing Authorization header
  * Expired access token
  * Invalid API key
  * Account locked or suspended
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Authenticated but lacks required permissions

  **Common causes:**

  * Insufficient role permissions
  * Attempting to access another merchant's data
  * Trying to perform owner-only actions
</ResponseField>

<ResponseField name="404" type="Not Found">
  Requested resource doesn't exist

  **Common causes:**

  * Invalid user ID
  * Role ID not found
  * API key doesn't exist
</ResponseField>

<ResponseField name="409" type="Conflict">
  Request conflicts with current state

  **Common causes:**

  * Email already registered
  * Role already assigned
  * API key name already exists
</ResponseField>

<ResponseField name="429" type="Too Many Requests">
  Rate limit exceeded

  **Response includes:**

  * `retry_after`: Seconds until next allowed request
  * Rate limit headers showing remaining quota
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Unexpected server error

  **Action:**

  * Retry the request
  * Contact support if persistent
</ResponseField>

***

## Rate Limit Headers

All responses include rate limit information:

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706097600
X-RateLimit-Endpoint: auth
```

<ParamField header="X-RateLimit-Limit" type="integer">
  Maximum requests allowed in the current window
</ParamField>

<ParamField header="X-RateLimit-Remaining" type="integer">
  Requests remaining in the current window
</ParamField>

<ParamField header="X-RateLimit-Reset" type="integer">
  Unix timestamp when the rate limit resets
</ParamField>

<ParamField header="X-RateLimit-Endpoint" type="string">
  Endpoint category (e.g., auth, payments, etc.)
</ParamField>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Merchant API" icon="store" href="/api/merchant-api">
    Manage merchants, teams, and settings
  </Card>

  <Card title="Payment API" icon="credit-card" href="/api/payment-api">
    Process payments and manage transactions
  </Card>

  <Card title="Quick Start" icon="rocket" href="/get-started/quick-start">
    Create your first payment intent
  </Card>

  <Card title="CLI Tool" icon="terminal" href="/tools/cli">
    Command-line interface for testing
  </Card>
</CardGroup>

***

**Questions?** Contact support at [redahaloubi8@gmail.com](mailto:redahaloubi8@gmail.com)