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

# Authentication

> API key authentication for programmatic access

RebelFi uses API key authentication for all programmatic API access.

## API Key Authentication

### Generating API Keys

There are two types of API keys:

| Type               | Scoping                    | Permissions                                                           | Use Case                                     |
| ------------------ | -------------------------- | --------------------------------------------------------------------- | -------------------------------------------- |
| **Profile-scoped** | Tied to one Wallet Profile | Read + Write (register wallets, plan operations, submit transactions) | Per-partner SDK integration                  |
| **Admin**          | Organization-wide          | Read-only (list wallets, view allocations, aggregate overview)        | Internal dashboards, cross-profile reporting |

### Profile-Scoped Keys

Profile-scoped keys can only register wallets and execute operations within their linked Wallet Profile. You must create a Wallet Profile before generating a profile-scoped key.

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Settings → Wallet Profiles** and create a profile (or use an existing one)
    2. Navigate to **Settings → API Keys**
    3. Click **Generate API Key**
    4. Provide a descriptive name (e.g., "Production SDK", "Dev Environment")
    5. Select the **Wallet Profile** to associate with this key
    6. Copy and securely store the key (shown only once)
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://api.rebelfi.io/api/core/apikeys/generate" \
      -H "Authorization: Bearer YOUR_DASHBOARD_JWT" \
      -H "Content-Type: application/json" \
      -d '{"name": "Production SDK", "walletProfileId": 1}'
    ```
  </Tab>
</Tabs>

### Admin Keys

Admin keys provide read-only access across all Wallet Profiles in your organization. They cannot register wallets, plan operations, or submit transactions. Use admin keys for internal tools that need aggregate metrics across all partners.

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Settings → API Keys**
    2. Click **Generate API Key**
    3. Provide a descriptive name (e.g., "Internal Dashboard")
    4. Select **Admin (read-only, all profiles)**
    5. Copy and securely store the key (shown only once)
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST "https://api.rebelfi.io/api/core/apikeys/generate" \
      -H "Authorization: Bearer YOUR_DASHBOARD_JWT" \
      -H "Content-Type: application/json" \
      -d '{"name": "Internal Dashboard", "isAdmin": true}'
    ```
  </Tab>
</Tabs>

<Info>
  Admin keys and `walletProfileId` are mutually exclusive — you cannot create an admin key scoped to a specific profile.
</Info>

### API Key Format

RebelFi API keys follow this format:

```
rfk_{sandbox|prod}_{random_string}
```

**Examples**:

* `rfk_sandbox_xxxxxxxxxxx` - Development key
* `rfk_prod_xxxxxxxxxxx` - Production key

### Using API Keys

Include the API key in the `x-api-key` header:

```bash theme={null}
curl -X GET "https://api.rebelfi.io/v1/venues" \
  -H "x-api-key: rfk_prod_xxxxxxxxxxx"
```

```typescript theme={null}
const response = await fetch('https://api.rebelfi.io/v1/venues', {
  headers: {
    'x-api-key': 'rfk_prod_xxxxxxxxxxx'
  }
});
```

### SDK Authentication

When using the TypeScript SDK:

```typescript theme={null}
import { RebelfiClient } from '@rebelfi/sdk';

const client = new RebelfiClient({
  apiKey: process.env.REBELFI_API_KEY
});
```

<Warning>
  Profile-scoped API keys can only operate on wallets registered within that profile. Admin keys are read-only across all profiles. Store all keys securely and rotate them regularly. Create separate keys for different environments (dev, staging, production).
</Warning>

## Security Best Practices

### API Key Management

<AccordionGroup>
  <Accordion title="Secure Storage" icon="vault">
    **DO**:

    * Store in environment variables
    * Use secrets management (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault)
    * Encrypt at rest

    **DON'T**:

    * Commit to version control
    * Store in code or configuration files
    * Share via email or chat
    * Log in plain text
  </Accordion>

  <Accordion title="Key Rotation" icon="rotate">
    Rotate API keys regularly:

    1. Generate new API key
    2. Deploy new key to production (blue/green deployment)
    3. Verify new key works
    4. Revoke old key
    5. Update documentation

    **Recommended frequency**: Every 90 days
  </Accordion>

  <Accordion title="Separate Keys Per Environment" icon="layer-group">
    Use different API keys for each environment:

    * Development: `rfk_sandbox_xxx`
    * Staging: `rfk_prod_xxx` (non-dev environments use production prefix)
    * Production: `rfk_prod_xxx`

    This limits blast radius if a key is compromised.
  </Accordion>
</AccordionGroup>

## Rate Limiting

RebelFi enforces rate limits per API key:

| Endpoint Type | Limit               |
| ------------- | ------------------- |
| Read (GET)    | 100 requests/minute |
| Write (POST)  | 20 requests/minute  |

### Handling Rate Limits

When rate limited, you'll receive a `429` status with `RATE_LIMIT_EXCEEDED` error code.

```typescript theme={null}
async function makeRequestWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || '60';
      console.log(`Rate limited. Retrying after ${retryAfter}s`);
      await new Promise(resolve => setTimeout(resolve, parseInt(retryAfter) * 1000));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock">
    **Cause**: Invalid or missing API key

    **Solution**:

    * Verify API key is correct
    * Ensure proper header format (`x-api-key: ...`)
    * Check key hasn't been revoked
    * Try generating a new API key
  </Accordion>

  <Accordion title="403 Forbidden" icon="ban">
    **Cause**: Valid credentials but access denied

    **Solution**:

    * Verify the Wallet Profile linked to this API key is enabled (not disabled or deleted)
    * Verify the wallet you are accessing belongs to the key's Wallet Profile
    * Check that the blockchain you are targeting is enabled in the Wallet Profile's `enabledChains` configuration
  </Accordion>

  <Accordion title="429 Rate Limit Exceeded" icon="gauge-high">
    **Cause**: Too many requests in time window

    **Solution**:

    * Implement exponential backoff
    * Reduce request frequency
    * Contact support for higher limits if needed
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Wallet Profiles" icon="layer-group" href="/guides/wallet-profiles">
    Set up wallet profiles and link your API key
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore authenticated API endpoints
  </Card>
</CardGroup>