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

# Authentication

> Authenticate API requests using Bearer tokens. Public key (pk_) for client-side SDK, secret key (sk_) for server-side with optional IP fraud prevention. Covers test vs live modes and API playground usage

## API Key Authentication

All API requests must be authenticated using your API key. You can find your API keys in the [Payviox Dashboard](https://dash.payviox.com) under the Developer section.

<Warning>
  **Keep your API keys secure!** Never share your Secret API Key in publicly accessible areas such as GitHub, client-side code, and so forth.
</Warning>

## API Key Types

Payviox provides two types of API keys for different integration scenarios:

<CardGroup cols={2}>
  <Card title="Public API Key" icon="globe">
    **For client-side / SDK integration**

    * Used in browser via JavaScript SDK
    * Client IP is automatically captured from the request
    * Safe to expose in frontend code
    * Ideal for: websites, single-page apps
  </Card>

  <Card title="Secret API Key" icon="key">
    **For server-side integration**

    * Used from your backend server
    * Allows providing client IP manually via `ip` parameter
    * Must NEVER be exposed in client-side code
    * Ideal for: APIs, mobile backends, server apps
  </Card>
</CardGroup>

### When to use which key?

| Use Case                         | Key Type   | IP Handling            |
| -------------------------------- | ---------- | ---------------------- |
| JavaScript SDK in browser        | Public Key | Auto-captured          |
| Direct API call from frontend    | Public Key | Auto-captured          |
| Backend creates session for user | Secret Key | Provide via `ip` param |
| Mobile app via backend           | Secret Key | Provide via `ip` param |
| Server-to-server integration     | Secret Key | Optional `ip` param    |

<Note>
  When using the **Secret API Key**, you can optionally provide the end-user's IP address using the `ip` parameter in the Create Session request. If provided, this IP will be validated when the user completes payment to prevent fraud.
</Note>

## Using the API Playground

Each endpoint in this documentation includes an interactive playground where you can test API calls directly from your browser.

<Steps>
  <Step title="Get Your API Key">
    Copy your API key from the [Payviox Dashboard](https://dash.payviox.com)
  </Step>

  <Step title="Open an Endpoint">
    Navigate to any endpoint page (e.g., Create Session)
  </Step>

  <Step title="Enter Your API Key">
    In the playground on the right, paste your API key in the **Authorization** field
  </Step>

  <Step title="Fill Request Body">
    Complete the required parameters in the request body
  </Step>

  <Step title="Send Request">
    Click **Send** to test the API call in real-time
  </Step>
</Steps>

<Tip>
  The playground automatically adds "Bearer " prefix to your API key in the Authorization header.
</Tip>

## How to Authenticate

Include your API key in the `Authorization` header of each request:

<CodeGroup>
  ```bash Public API Key (Client-side) theme={null}
  Authorization: Bearer pk_live_xxxxxxxxxxxx
  ```

  ```bash Secret API Key (Server-side) theme={null}
  Authorization: Bearer sk_live_xxxxxxxxxxxx
  ```
</CodeGroup>

<Tip>
  Public keys typically start with `pk_` and Secret keys with `sk_`. Both work with the same endpoints, but Secret keys unlock additional parameters like `ip`.
</Tip>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.payviox.com/session \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
      "amount": 10000,
      "currency": "USD",
      "customer": "customer_abc123",
      "order_id": "order_123",
      "items": [
        {
          "name": "Product 1",
          "quantity": 1,
          "price": 10000
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.payviox.com/session', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 10000,
      currency: 'USD',
      customer: 'customer_abc123',
      order_id: 'order_123',
      items: [
        {
          name: 'Product 1',
          quantity: 1,
          price: 10000
        }
      ]
    })
  });

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

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

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  data = {
      'amount': 10000,
      'currency': 'USD',
      'customer': 'customer_abc123',
      'order_id': 'order_123',
      'items': [
          {
              'name': 'Product 1',
              'quantity': 1,
              'price': 10000
          }
      ]
  }

  response = requests.post(
      'https://api.payviox.com/session',
      headers=headers,
      json=data
  )

  print(response.json())
  ```

  ```php PHP theme={null}
  <?php

  $apiKey = 'YOUR_API_KEY';
  $url = 'https://api.payviox.com/session';

  $data = [
      'amount' => 10000,
      'currency' => 'USD',
      'customer' => 'customer_abc123',
      'order_id' => 'order_123',
      'items' => [
          [
              'name' => 'Product 1',
              'quantity' => 1,
              'price' => 10000
          ]
      ]
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer ' . $apiKey,
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $result = json_decode($response, true);
  print_r($result);
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  uri = URI('https://api.payviox.com/session')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer YOUR_API_KEY'
  request['Content-Type'] = 'application/json'

  request.body = {
    amount: 10000,
    currency: 'USD',
    customer: 'customer_abc123',
    order_id: 'order_123',
    items: [
      {
        name: 'Product 1',
        quantity: 1,
        price: 10000
      }
    ]
  }.to_json

  response = http.request(request)
  puts JSON.parse(response.body)
  ```
</CodeGroup>

## API Key Management

### Getting Your API Keys

1. Log in to your [Payviox Dashboard](https://dash.payviox.com)
2. Navigate to **Developer** > **API Keys**
3. Copy your keys:
   * **Public API Key**: For frontend/SDK integration
   * **Secret API Key**: For backend/server-side integration

### Regenerating API Keys

If your API key has been compromised, you can regenerate it from the dashboard:

<Steps>
  <Step title="Access Developer Settings">
    Go to **Developer** > **API Keys** in your dashboard
  </Step>

  <Step title="Regenerate Key">
    Click **Regenerate API Key**
  </Step>

  <Step title="Update Your Integration">
    Update your integration with the new API key
  </Step>
</Steps>

<Warning>
  When you regenerate an API key, the old key will stop working immediately. Make sure to update your integration before regenerating.
</Warning>

## Error Responses

If authentication fails, you'll receive the following response:

```json theme={null}
{
  "error": "Unauthorized"
}
```

This error is returned when the `Authorization` header is missing, the API key is invalid, or the API key has been regenerated. Check your API key and try again.

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="lock">
    Store your API keys in environment variables, never hardcode them
  </Card>

  <Card title="Different Keys for Different Environments" icon="server">
    Use separate API keys for development, staging, and production
  </Card>

  <Card title="Rotate Keys Regularly" icon="rotate">
    Periodically regenerate your API keys for enhanced security
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Keep track of your API usage in the dashboard
  </Card>
</CardGroup>