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

# Authentication

> All API requests must be authenticated using API keys. Every request requires two headers: `apiKey` and `appId`

## Authentication Headers

| Header   | Required | Format                | Description                 |
| -------- | -------- | --------------------- | --------------------------- |
| `apiKey` | Yes      | `xf_` prefixed string | Your unique API key         |
| `appId`  | Yes      | UUID format           | Your application identifier |

### Getting Your API Credentials

<Steps>
  <Step title="Log into Dashboard">
    Navigate to [dashboard.xentfi.com](https://dashboard.xentfi.com) and log in.
  </Step>

  <Step title="Go to API Keys">
    Click **Settings** → **API Keys** in the left sidebar.
  </Step>

  <Step title="Generate New Key">
    Click **Generate New API Key**, enter a name, and select environment.
  </Step>

  <Step title="Copy Credentials">
    Copy your `apiKey` and `appId`. **Store them securely** - you won't see the key again!
  </Step>
</Steps>

## Making Authenticated Requests

Include both headers in every API request:

<CodeGroup>
  ```bash theme={null}
  curl -X GET https://api.xentfi.com/v1/master-wallets \
    -H "apiKey: xf_abc123def456..." \
    -H "appId: app_123e4567-e89b-12d3-a456-426614174000"
  ```

  ```javascript theme={null}
  fetch('https://api.xentfi.com/v1/master-wallets', {
    headers: {
      'apiKey': 'xf_abc123def456...',
      'appId': 'app_123e4567-e89b-12d3-a456-426614174000'
    }
  });
  ```

  ```python theme={null}
  import requests

  headers = {
      'apiKey': 'xf_abc123def456...',
      'appId': 'app_123e4567-e89b-12d3-a456-426614174000'
  }

  response = requests.get('https://api.xentfi.com/v1/master-wallets', headers=headers)
  ```
</CodeGroup>

## Authentication Response

### Success (200)

When authentication succeeds, you receive the requested data.

### Failure (401)

When authentication fails:

<ResponseExample>
  ```json theme={null}
  {
      "success": false,
      "error": {
          "code": "UNAUTHORIZED",
          "message": "Invalid API key or appId",
          "timestamp": "2024-01-15T10:30:00.000Z",
          "requestId": "req_123e4567-e89b-12d3-a456-426614174000"
      }
  }
  ```
</ResponseExample>

## API Key Types

| Type           | Environment | Use Case                |
| -------------- | ----------- | ----------------------- |
| **Sandbox**    | Testnet     | Development and testing |
| **Production** | Mainnet     | Live transactions       |

### Sandbox Keys

* Use for development and testing
* Testnet networks only
* Higher rate limits
* No real funds required

### Production Keys

* Use for live transactions
* Mainnet networks only
* Standard rate limits
* Real funds transfer

## API Key Scopes

| Scope   | Permissions            | Use Case              |
| ------- | ---------------------- | --------------------- |
| `read`  | GET endpoints only     | Monitoring, analytics |
| `write` | POST, PUT, DELETE      | Full API access       |
| `admin` | All operations + admin | Account management    |

## Security Best Practices

<Warning>
  Never share your API keys publicly. Always use environment variables.
</Warning>

| Practice                   | Importance | Description                         |
| -------------------------- | ---------- | ----------------------------------- |
| **Environment variables**  | Critical   | Never hardcode keys in code         |
| **Regular rotation**       | High       | Rotate keys every 90 days           |
| **Environment separation** | High       | Different keys for dev/prod         |
| **Least privilege**        | High       | Grant minimum required scopes       |
| **Immediate revocation**   | Critical   | Revoke compromised keys immediately |
| **Audit logging**          | Medium     | Monitor key usage                   |

## Key Rotation

### When to Rotate

* Every 90 days (recommended)
* Team member departure
* Suspected compromise
* Security audit requirement

### Rotation Process

```mermaid theme={null}
flowchart LR
    Generate[Generate New Key] --> Update[Update Applications]
    Update --> Verify[Verify Working]
    Verify --> Deprecate[Deprecate Old Key]
    Deprecate --> Remove[Remove Old Key]
```

### Rotating via API

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.xentfi.com/v1/api-keys/{keyId}/rotate \
    -H "apiKey: current-api-key" \
    -H "orgId: your-org-id" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

## Key Revocation

If a key is compromised, revoke it immediately:

<CodeGroup>
  ```bash theme={null}
  curl -X DELETE https://api.xentfi.com/v1/api-keys/{keyId} \
    -H "apiKey: your-admin-key" \
    -H "orgId: your-org-id"
  ```
</CodeGroup>

## Environment Setup

### Development Environment (.env)

```bash theme={null}
# Sandbox Environment
XENTFI_API_KEY=xf_sandbox_abc123...
XENTFI_ORG_ID=orgId__123e4567...
XENTFI_ENVIRONMENT=sandbox
XENTFI_BASE_URL=https://api.xentfi.com/v1
```

### Production Environment

```bash theme={null}
# Production Environment
XENTFI_API_KEY=xf_prod_xyz789...
XENTFI_ORG_ID=aorgId_789abc...
XENTFI_ENVIRONMENT=production
XENTFI_BASE_URL=https://api.xentfi.com/v1
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized - Invalid API key">
    **Possible causes:**

    * API key is incorrect
    * API key has been revoked
    * Using sandbox key on production

    **Solutions:**

    * Verify API key in dashboard
    * Generate new key if needed
    * Check environment matching
  </Accordion>

  <Accordion title="401 Unauthorized - Missing headers">
    **Solution:** Ensure both `apiKey` and `appId` headers are included in every request.
  </Accordion>

  <Accordion title="403 Forbidden - Insufficient scope">
    **Solution:** Your API key doesn't have permission for this operation. Generate a key with required scopes.
  </Accordion>
</AccordionGroup>

## Rate Limits by Key Type

| Key Type              | Requests/Second | Requests/Minute | Requests/Day |
| --------------------- | --------------- | --------------- | ------------ |
| Sandbox (Starter)     | 5               | 60              | 10,000       |
| Sandbox (Pro)         | 20              | 300             | 100,000      |
| Production (Starter)  | 5               | 60              | 10,000       |
| Production (Pro)      | 20              | 300             | 100,000      |
| Production (Business) | 50              | 1,000           | 1,000,000    |

## Related Resources

* [Rate Limits Guide](/getting-started/rate-limits) - Detailed rate limit information
* [Error Handling](/api-reference/errors) - Common authentication errors
* [Security Overview](/essentials/security) - Security best practices