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

# Authentication Process

> Secure your API requests with API key authentication

## Overview

The Waypay API uses API keys to authenticate requests. You can view and manage your API keys in the [Waypay Dashboard](https://dashboard.waypay.com/settings/api).

<Warning>
  Your API keys carry many privileges, so keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, or anywhere else that could expose them.
</Warning>

## API Keys

Waypay provides two types of API keys:

<CardGroup cols={2}>
  <Card title="Test Keys" icon="flask">
    Use these keys during development and testing. They start with `pk_test_`
  </Card>

  <Card title="Live Keys" icon="circle-check">
    Use these keys in production. They start with `pk_live_`
  </Card>
</CardGroup>

### Key Characteristics

* **Test keys** process transactions in test mode - no real money is moved
* **Live keys** process real transactions and charge actual payment methods
* Both environments have separate databases and don't share data
* API behavior is identical in both environments

## Authentication Method

Include your API key in the `SWICH-API-Key` header:

```
SWICH-API-Key: YOUR_API_KEY
```

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/TXN123456 \
    --header 'SWICH-API-Key: pk_test_xxxxxxxxxxxxx'
  ```

  ```javascript Node.js theme={null}
  const fetch = require('node-fetch');

  const response = await fetch(
    'https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/TXN123456',
    {
      method: 'GET',
      headers: {
        'SWICH-API-Key': process.env.WAYPAY_API_KEY
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ.get('WAYPAY_API_KEY')

  response = requests.get(
      'https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/TXN123456',
      headers={
          'SWICH-API-Key': api_key
      }
  )

  data = response.json()
  ```

  ```php PHP theme={null}
  <?php
  $api_key = getenv('WAYPAY_API_KEY');

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/TXN123456",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "SWICH-API-Key: " . $api_key
    ],
  ]);

  $response = curl_exec($curl);
  $data = json_decode($response, true);

  curl_close($curl);
  ?>
  ```
</CodeGroup>

## Storing API Keys Securely

### Environment Variables (Recommended)

Store your API keys in environment variables:

<CodeGroup>
  ```bash Linux/macOS theme={null}
  export WAYPAY_API_KEY="pk_live_xxxxxxxxxxxxx"
  ```

  ```powershell Windows PowerShell theme={null}
  $env:WAYPAY_API_KEY="pk_live_xxxxxxxxxxxxx"
  ```

  ```bash .env File theme={null}
  WAYPAY_API_KEY=pk_live_xxxxxxxxxxxxx
  ```
</CodeGroup>

### Best Practices

<Steps>
  <Step title="Use Environment Variables">
    Never hardcode API keys in your source code. Use environment variables or secure configuration management.
  </Step>

  <Step title="Separate Keys by Environment">
    Use different API keys for development, staging, and production environments.
  </Step>

  <Step title="Restrict Key Permissions">
    Create separate keys with limited permissions for different services or applications.
  </Step>

  <Step title="Rotate Keys Regularly">
    Periodically rotate your API keys and immediately revoke compromised keys.
  </Step>

  <Step title="Use Server-Side Only">
    Never include API keys in client-side code (JavaScript, mobile apps) where they can be extracted.
  </Step>
</Steps>

## Authentication Errors

### 401 Unauthorized

This error occurs when:

* No `SWICH-API-Key` header is provided
* The API key is invalid or has been revoked
* The API key format is incorrect

**Example Error Response:**

```json theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing authentication token"
}
```

**Solutions:**

1. Verify your API key is correct and active
2. Ensure the header format is exactly: `SWICH-API-Key: YOUR_API_KEY`
3. Check that you're using the correct key for the environment (test vs live)
4. Confirm the key hasn't been revoked in the dashboard

### 403 Forbidden

This error occurs when:

* The API key doesn't have permission for the requested resource
* The account is suspended or restricted

**Example Error Response:**

```json theme={null}
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions to access this resource"
}
```

## API Key Management

### Creating API Keys

1. Log in to your [Waypay Dashboard](https://dashboard.waypay.com)
2. Navigate to **Settings** → **API Keys**
3. Click **Create API Key**
4. Choose the environment (Test or Live)
5. Set permissions and restrictions
6. Save the key securely - it will only be shown once

### Revoking API Keys

If you suspect a key has been compromised:

1. Go to **Settings** → **API Keys** in your dashboard
2. Find the compromised key
3. Click **Revoke**
4. Create a new key to replace it
5. Update your application with the new key

<Warning>
  Revoking a key will immediately stop all API requests using that key. Ensure you have a rollover plan before revoking keys used in production.
</Warning>

## Testing Authentication

Test your authentication setup with a simple API call:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://gateway.dev.waypay.live/Gateway/v1/Settlements/schedule \
    --header 'SWICH-API-Key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const testAuth = async () => {
    try {
      const response = await fetch(
        'https://gateway.dev.waypay.live/Gateway/v1/Settlements/schedule',
        {
          headers: {
            'SWICH-API-Key': process.env.WAYPAY_API_KEY
          }
        }
      );
      
      if (response.ok) {
        console.log('✓ Authentication successful');
      } else {
        console.error('✗ Authentication failed:', response.status);
      }
    } catch (error) {
      console.error('✗ Request failed:', error.message);
    }
  };

  testAuth();
  ```

  ```python Python theme={null}
  import os
  import requests

  def test_auth():
      api_key = os.environ.get('WAYPAY_API_KEY')
      
      response = requests.get(
          'https://gateway.dev.waypay.live/Gateway/v1/Settlements/schedule',
          headers={'SWICH-API-Key': api_key}
      )
      
      if response.status_code == 200:
          print('✓ Authentication successful')
      else:
          print(f'✗ Authentication failed: {response.status_code}')

  test_auth()
  ```
</CodeGroup>

## Security Recommendations

<AccordionGroup>
  <Accordion title="Use HTTPS Only">
    Always use HTTPS for API requests. Never send API keys over unencrypted HTTP connections.
  </Accordion>

  <Accordion title="Implement Key Rotation">
    Rotate API keys every 90 days or immediately after team member departures.
  </Accordion>

  <Accordion title="Monitor API Usage">
    Regularly review API logs in your dashboard for unusual activity.
  </Accordion>

  <Accordion title="Principle of Least Privilege">
    Grant each API key only the permissions it needs to perform its function.
  </Accordion>

  <Accordion title="Secure Key Storage">
    Use secure key management services (AWS KMS, Azure Key Vault, HashiCorp Vault) in production.
  </Accordion>
</AccordionGroup>

## Additional Headers

While the `SWICH-API-Key` header is required, you may also include optional headers:

### Content-Type

```
Content-Type: application/json
```

Required for POST, PUT, and PATCH requests with JSON bodies.

### Idempotency-Key

```
Idempotency-Key: unique-operation-id-123
```

Optional header to safely retry requests without duplicate processing.

### User-Agent

```
User-Agent: MyApp/1.0.0
```

Optional header to identify your application in logs and support tickets.

## Next Steps

<CardGroup cols={2}>
  <Card title="Make Your First Payment" icon="credit-card" href="/api-reference/endpoints/payment-initiate">
    Learn how to create a payment checkout session
  </Card>

  <Card title="Handle Webhooks" icon="webhook" href="/guides/webhooks">
    Set up webhook endpoints for event notifications
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/endpoints/errors">
    Learn about API error codes and handling
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Complete integration tutorial
  </Card>
</CardGroup>