> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/getting-started/authentication.md).

# Authentication

Use HTTP Basic authentication on every public API request.

## Quick reference

| Item                | Value                                            |
| ------------------- | ------------------------------------------------ |
| Scheme              | `Basic`                                          |
| Header              | `Authorization: Basic <base64(clientId:apiKey)>` |
| Testing base URL    | `https://api.testing.plexo.com.uy`               |
| Production base URL | `https://api.plexo.com.uy`                       |

{% hint style="warning" %}
Use API credentials only from your backend. Do not expose them in browser code, mobile apps, or public repositories.
{% endhint %}

## Build the header

Concatenate your `clientId`, a colon, and your `apiKey`, then Base64 encode the result.

```
clientId:apiKey
```

```
Authorization: Basic base64(clientId:apiKey)
```

Example:

```bash
printf '%s' 'test_12345:sk_test_abcdef123456789' | base64
```

## Example request

```bash
curl -X POST https://api.testing.plexo.com.uy/v1/payments \
  -H "Authorization: Basic <base64(clientId:apiKey)>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 67890,
    "referenceId": "order-1001",
    "invoiceNumber": "1001",
    "amount": {
      "total": 100.00,
      "currency": "UYU"
    },
    "paymentMethod": {
      "source": "card",
      "card": {
        "number": "{{TEST_CARD_NUMBER}}",
        "expMonth": 12,
        "expYear": 2028,
        "cvc": "{{TEST_CARD_CVC}}",
        "cardholder": {
          "firstName": "Test",
          "lastName": "User",
          "email": "test.user@example.com"
        }
      }
    },
    "browserDetails": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0"
    },
    "capture": {
      "method": "automatic"
    }
  }'
```

## Credentials

Request your testing or production credentials from Plexo support. Keep a separate `clientId`, `apiKey`, and `merchantId` for each environment.

## Common errors

### 401 Unauthorized

The request is not authenticated.

Common causes:

* Missing `Authorization` header
* Wrong `clientId` or `apiKey`
* Invalid Base64 value
* Using testing credentials against production, or the reverse

Example response:

```json
{
  "type": "api-error",
  "status": 401,
  "code": "unauthorized",
  "message": "Invalid credentials",
  "traceId": "0HMVG9K3R5T4J:00000001"
}
```

### 403 Forbidden

The credentials are valid, but the request is not allowed for that resource or merchant.

Example response:

```json
{
  "type": "api-error",
  "status": 403,
  "code": "forbidden",
  "message": "Access denied",
  "traceId": "0HMVG9K3R5T4J:00000002"
}
```

## Minimal security rules

* Store credentials in environment variables or a secrets manager.
* Rotate API keys periodically.
* Use different credentials for testing and production.
* Never send API credentials from client-side applications.

## Related resources

* [API Endpoints](/rest-api/getting-started/readme.md)
* [API Explorer](/rest-api/tools/api-explorer.md)
* [Payment Processing Guide](/rest-api/payments/payment-processing.md)
* [Error Codes Reference](/rest-api/reference/error-codes.md)