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

# Authentication

> How to authenticate requests to the Sales Partner API using your API key.

All API requests require authentication using an **API key**. This key is unique to each sales partner and must be included in every request to ensure secure and authorized access to the Sales Partner API.

## What is an API Key?

An API key is a secret token that identifies your application or system when making requests to Compago's Sales Partner API. It ensures that only authorized systems can query payment data, retrieve reports, or access any API functionality.

Keep your API key secure and never expose it in public client-side code.

## How to Generate an API Key

To create an API key:

1. Sign in to your Sales Partner Dashboard.
2. Navigate to **Configuraciones** > **Desarrollador**.
3. Click **Crear API Key**.
4. Enter a name for the key (e.g., `Production Dashboard`, `Reporting Integration`).
5. Click **Crear** and **copy the key immediately**.

<Warning>
  Your API key will only be shown once when created. Make sure to store it securely before closing the dialog.
</Warning>

You can delete keys at any time from the same dashboard section by clicking **Eliminar** on the key you want to remove.

## Using the API Key in Requests

Every request to a protected endpoint must include your API key in the `x-api-key` header.

### Header Format

```
x-api-key: YOUR_API_KEY
```

Here's an example using `curl`:

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?limit=10"
```

If the API key is missing or invalid, you will receive a `401 Unauthorized` response.

### Example with Code

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.honor.compago.com/api/developer/payment?limit=10',
    {
      headers: {
        'x-api-key': process.env.COMPAGO_API_KEY
      }
    }
  );

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

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

  response = requests.get(
      'https://api.honor.compago.com/api/developer/payment',
      headers={'x-api-key': os.environ['COMPAGO_API_KEY']},
      params={'limit': 10}
  )

  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.honor.compago.com/api/developer/payment?limit=10');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'x-api-key: ' . getenv('COMPAGO_API_KEY')
  ]);

  $response = curl_exec($ch);
  $data = json_decode($response, true);
  curl_close($ch);

  print_r($data);
  ?>
  ```
</CodeGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Keep your API key secret">
    Never expose your API key in client-side code, public repositories, or browser requests. Always make API calls from your server-side application.

    ```javascript theme={null}
    // WRONG - API key exposed in browser
    fetch('/api/developer/payment', {
      headers: { 'x-api-key': 'sk_live_abc123...' }
    });

    // CORRECT - API call from your server
    app.get('/my-payments', async (req, res) => {
      const data = await fetch('https://api.honor.compago.com/api/developer/payment', {
        headers: { 'x-api-key': process.env.COMPAGO_API_KEY }
      });
      res.json(await data.json());
    });
    ```
  </Accordion>

  <Accordion title="Use environment variables">
    Store your API key in environment variables rather than hardcoding it in your source code.

    ```bash theme={null}
    # .env file (never commit this file)
    COMPAGO_API_KEY=your_api_key_here
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Periodically generate new API keys and revoke old ones. This limits the impact if a key is accidentally exposed.
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Create different API keys for development, staging, and production environments. This way, revoking a development key does not affect your production integration.
  </Accordion>
</AccordionGroup>

## Access Scope

API keys are scoped to your sales partner account. This means:

* You can only access payment data for organizations that belong to your sales partner account.
* Even if you provide an `organizationId` filter, the API will only return results for organizations under your account.
* There is no way to access data belonging to other sales partners or organizations outside your scope.

## Error Responses

| Status Code        | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `401 Unauthorized` | API key is missing, invalid, or has been revoked            |
| `403 Forbidden`    | API key does not have permission for the requested resource |

### Example Error

```bash theme={null}
curl "https://api.honor.compago.com/api/developer/payment"
# No x-api-key header
```

```
HTTP/1.1 401 Unauthorized
Unauthorized
```