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

# Authentication

> How to authenticate with the PCX API using API keys or Cognito JWTs

## Overview

PCX supports two credential types — **API keys** for server-to-server integrations and **JWTs** for user-facing flows. Both use the same underlying mechanism: PCX's API Gateway runs a custom Lambda Authorizer that inspects two headers on every request.

**Both headers must always be present.** Whichever header is not being used for authentication must be sent with the literal string value `NONE`. The authorizer ignores headers with the value `NONE` — it does not treat them as credentials.

| Header          | API key flow            | JWT flow                |
| --------------- | ----------------------- | ----------------------- |
| `Authorization` | `NONE` (literal string) | `Bearer <cognito_jwt>`  |
| `X-Api-Key`     | `<your_api_key>`        | `NONE` (literal string) |

<Warning>
  Sending only one header, or omitting the unused header entirely, will result in a `401 Unauthorized` response.
</Warning>

***

## API key authentication (server-to-server)

Use this for backend integrations and automated workflows. Send your API key in `X-Api-Key` and set `Authorization` to the literal string `NONE`.

```bash theme={null}
curl https://prod-api.pcxpay.com/v1/organizations/{org_id} \
  -H "X-Api-Key: your_api_key_here" \
  -H "Authorization: NONE"
```

Generate keys from **Dashboard → Settings → API Keys**.

<Warning>
  Never expose API keys in client-side code or public repositories. Rotate immediately if compromised.
</Warning>

***

## JWT authentication (user-facing flows)

Use this when an end user has authenticated through Cognito. Send the JWT as a Bearer token in `Authorization` and set `X-Api-Key` to the literal string `NONE`.

```bash theme={null}
curl https://prod-api.pcxpay.com/v1/transactions \
  -H "Authorization: Bearer eyJraWQ..." \
  -H "X-Api-Key: NONE"
```

***

## API playground note

Mintlify's API playground sends `X-Api-Key` as the auth header. When testing **JWT flows** in the playground, manually add both headers — set `Authorization` to `Bearer <your_jwt>` and `X-Api-Key` to `NONE`.

***

## Errors

| Status | Meaning                                        |
| ------ | ---------------------------------------------- |
| `401`  | Missing, invalid, or incomplete headers        |
| `403`  | Valid credentials but insufficient permissions |

```json theme={null}
{
  "status": "error",
  "message": "Unauthorized"
}
```