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

# Authentication

> How to authenticate your requests with the PaveWay API.

PaveWay uses API keys to authenticate requests. You can manage your API keys in the Business Dashboard.

## Getting Your Keys

To protect your business data, PaveWay requires a few security steps before keys can be issued:

1. **Register your Business**: Complete your KYC and business setup on the [Business Portal](https://business.pavewaygroup.com).
2. **Secure your Account**: Head to **Settings > Security** and enable **Two-Factor Authentication (2FA)**.
3. **Reveal Keys**: Go to **Developers > API Keys**. Your Secret Keys will only be displayed once—make sure to store them in a secure environment variable or vault.

## Key Types

PaveWay provides three types of keys to handle different integration scenarios:

| Key Type           | Prefix      | Usage                                                                |
| :----------------- | :---------- | :------------------------------------------------------------------- |
| **Secret Key**     | `sk_...`    | Used for server-to-server API calls. Keep this secure!               |
| **Public Key**     | `pk_...`    | Used in client-side SDKs. Never expose this key in client-side code. |
| **Webhook Secret** | `whsec_...` | Used to verify that events sent to your server are from PaveWay.     |

## Environments

PaveWay provides two distinct environments to ensure you can build and test safely.

### Switching Environments

To toggle between environments, you must update two things in your code:

1. **The API Key**: Use your `sk_test_...` key for testing and your `sk_live_...` key for production.
2. **The Base URL**:
   * **Live**: `https://api.pavewaygroup.com/v1`
   * **Test**: `https://paveway-gateway-adwfci84.uc.gateway.dev/v1`

| Environment           | Key Prefix | Base URL                                             |
| :-------------------- | :--------- | :--------------------------------------------------- |
| **Sandbox (Test)**    | `sk_test_` | `https://paveway-gateway-adwfci84.uc.gateway.dev/v1` |
| **Production (Live)** | `sk_live_` | `https://api.pavewaygroup.com/v1`                    |

## Including Keys in Requests

For server-side requests (Secret Keys), include your key in the `Authorization` header as a Bearer token.

```bash theme={null}
curl https://api.pavewaygroup.com/v1/payment-intents \
  -H "Authorization: Bearer sk_test_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

### X-API-KEY Header (Legacy/Alternative)

Some endpoints also support the custom `x-api-key` header for cases where Bearer authentication is not suitable:

```http theme={null}
x-api-key: sk_test_your_secret_key_here
```

## Rate Limiting

To ensure API stability, PaveWay enforces rate limits on all endpoints. Limits are applied per API key and per IP address.

* **Standard Endpoints**: 60 requests per minute.
* **Payment Creation**: 20 requests per minute.
* **Card Tokenization**: 10 requests per minute.

If you exceed these limits, the API will return a `429 Too Many Requests` error. If you require higher limits for your production application, please contact our support team.

> \[!CAUTION]
> Never share your Secret Keys or include them in client-side code (browsers, mobile apps). If a key is compromised, rotate it immediately in the Business Dashboard.