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

# Authentication

> Learn how to authenticate your API requests with FossaPay

## API Authentication

FossaPay uses API keys to authenticate requests. You can view and manage your API keys in the [FossaPay Dashboard](https://dashboard.fossapay.com/settings?tab=api-keys).

<Warning>
  **Keep your API keys secure!** Your secret keys can perform any API request without restriction. Keep them secure and never share them publicly or commit them to version control.
</Warning>

## API Key Types

FossaPay provides two types of API keys:

<CardGroup cols={2}>
  <Card color="#0080FF" title="Test Keys" icon="flask">
    Use test keys in sandbox mode to test your integration without affecting real data or transactions.
  </Card>

  <Card color="#0080FF" title="Live Keys" icon="circle-check">
    Use live keys in production to process real transactions and manage actual customer data.
  </Card>
</CardGroup>

## Getting Your API Keys

1. Sign up or log in to your [FossaPay Dashboard](https://dashboard.fossapay.com)
2. Navigate to **Settings** → **API Keys**
3. Copy your **Test Key** or **Live Key**
4. Use the test keys for development and live keys for production

## Making Authenticated Requests

Include your secret key in the `x-api-key` header of your API requests:

```bash theme={null}
curl https://api-production.fossapay.com/api/v1/wallets/fiat/create \
  -H "x-api-key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
```

### Authentication Header Format

```
x-api-key: fp_live_1234567890abcdef
```

## API Key Format

FossaPay API keys follow this format:

* **Test Key**: `fp_test_sk_xxxxxxxxxxxxxxxx`
* **Live Key**: `fp_live_sk_xxxxxxxxxxxxxxxx`

## Request Headers

Every API request should include these headers:

| Header              | Value                     | Required    |
| ------------------- | ------------------------- | ----------- |
| `x-api-key`         | `YOUR_SECRET_KEY`         | Yes         |
| `Content-Type`      | `application/json`        | Yes         |
| `X-Idempotency-Key` | Unique request identifier | Recommended |

### Example Request

```javascript theme={null}
const axios = require('axios');

const response = await axios.post(
  'https://api-production.fossapay.com/api/v1/wallets/fiat/create',
  {
    customerId: 'cus_123456789',
    walletName: 'Main Wallet',
    walletReference: 'wallet_ref_001'
  },
  {
    headers: {
      'x-api-key': 'fp_test_sk_xxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
      'X-Idempotency-Key': 'unique-request-id-12345'
    }
  }
);
```

## Idempotency

To prevent duplicate requests, use the `X-Idempotency-Key` header. If you make the same request twice with the same idempotency key, FossaPay will return the same response without processing the request again.

```bash theme={null}
curl https://api-production.fossapay.com/api/v1/transfers/fiat/inter-bank \
  -H "x-api-key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: payout-20240119-001" \
  -d '{
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "destinationBankCode": "044",
    "destinationAccountName": "JOHN DOE",
    "destinationAccountNumber": "1234567890",
    "destinationBankName": "ACCESS BANK",
    "reference": "TRF-2024-001",
    "remarks": "Salary payment",
    "amount": 10000
  }'
```

<Tip>
  Use idempotency keys for all POST requests, especially for payouts, to prevent accidental duplicate transactions.
</Tip>

## Error Handling

### Authentication Errors

If authentication fails, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "success": false,
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

Common authentication errors:

| Error Code               | Description                            |
| ------------------------ | -------------------------------------- |
| `INVALID_API_KEY`        | The API key provided is invalid        |
| `EXPIRED_API_KEY`        | The API key has expired                |
| `MISSING_API_KEY`        | No API key was provided                |
| `TEST_KEY_IN_PRODUCTION` | Attempted to use test key in live mode |
| `LIVE_KEY_IN_TEST`       | Attempted to use live key in test mode |

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store Keys Securely">
    * Never hardcode API keys in your application
    * Use environment variables or secure key management systems
    * Rotate keys regularly
  </Accordion>

  <Accordion title="Use HTTPS Only">
    * All API requests must use HTTPS
    * HTTP requests will be rejected
  </Accordion>

  <Accordion title="Restrict API Key Access">
    * Limit API key permissions to only what's needed
    * Use different keys for different environments
    * Monitor API key usage in your dashboard
  </Accordion>

  <Accordion title="Implement Rate Limiting">
    * FossaPay implements rate limiting to protect against abuse
    * Current limit: 100 requests per minute
    * Contact support for higher limits
  </Accordion>
</AccordionGroup>

## Testing Authentication

Test your authentication setup with this simple request:

```bash theme={null}
curl https://api-production.fossapay.com/api/v1/customers \
  -H "x-api-key: YOUR_SECRET_KEY"
```

**Successful Response:**

```json theme={null}
{
  "success": true,
  "message": "List of customers retrieved successfully",
  "data": []
}
```

## Next Steps

<CardGroup cols={2}>
  <Card color="#0080FF" title="Create a Customer" icon="code" href="/concepts/customers">
    Make your first API call
  </Card>
</CardGroup>