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

# Authentication

> Authenticate your requests to the TapiPay Facade API with your API key and your TAPI token, and test your first endpoint.

The Facade API uses **two credentials** on every request: your **API key** (`x-api-key` header) and your **TAPI token** (`x-authorization-token` header). Both are required: if either is missing, the request is rejected with `401`.

## The two credentials

<ResponseField name="x-api-key" type="string" required>
  Your integration's API key on the Tapi API Gateway. Tapi provisions it for you and it is **different per environment** (development, staging, production). It identifies your application and controls access to the gateway.
</ResponseField>

<ResponseField name="x-authorization-token" type="string" required>
  Your **TAPI token** (a JWT), the same one you already use with the rest of the Tapi platform. It is sent **without** the `Bearer` prefix.
</ResponseField>

<Warning>
  The token goes in `x-authorization-token`, **not** the standard `Authorization: Bearer`, and without the "Bearer" prefix. It is a Tapi-specific header used to maintain compatibility with the rest of the platform.
</Warning>

## Get your TAPI token

The TAPI token (a JWT) comes from the Tapi login, the same one you already use with the rest of the platform. Send your credentials and you will receive an `accessToken`:

```bash theme={null}
curl --request POST \
  --url 'https://login.<environment>.tapila.cloud/login' \
  --header 'x-api-key: YOUR_LOGIN_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientUsername": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD"
  }'
```

The response includes the `accessToken` (your TAPI token) and a `refreshToken`:

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

<Note>
  The `accessToken` expires after \~4 hours. When it expires, log in again (or use the `refreshToken` with the standard Tapi flow). The login `x-api-key` is your integration's key and is **not** the same one you use against the Facade.
</Note>

## Test an endpoint

<Tabs>
  <Tab title="From the playground">
    In the [API Reference](/api-reference), open any endpoint and use the **Send** button:

    1. Pick the **server** in the selector.
    2. Paste your `x-api-key` and your `x-authorization-token` into the authentication fields.
    3. Fill in the parameters and press **Send**.

    Your credentials are stored **only in your browser** and are reused across all endpoints.
  </Tab>

  <Tab title="With curl">
    ```bash theme={null}
    curl --request GET \
      --url '<BASE_URL>/contacts?page=1&limit=10' \
      --header 'x-api-key: YOUR_API_KEY' \
      --header 'x-authorization-token: YOUR_TAPI_TOKEN'
    ```

    Replace `<BASE_URL>` with the URL of the environment you are testing against.
  </Tab>
</Tabs>

<Warning>
  Never share or commit your `x-api-key` or your token to a repository: they are sensitive credentials. In the playground they live only in your browser; in curl, pass them as environment variables.
</Warning>

## What your token resolves for you

Starting from your token, Tapi identifies your account and internally resolves the entire internal model (company, modalities, etc.). You work with clear business concepts and never need to send or know that internal data.

## Authentication errors

When the API key or the token is missing, invalid, or expired, the API responds with `401` and this structure:

```json theme={null}
{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Missing or invalid TAPI token"
  },
  "requestId": "req_a1b2c3d4"
}
```

Every API error follows the same shape: an `error` object with `code` and `message`, plus a `requestId` that you can share with support to trace the request.

## Expired token

If your token expired, refresh it with the same flow you already use for the rest of the Tapi API and retry the request. The Facade has no refresh mechanism of its own: it reuses the one from the Tapi ecosystem.

<Note>
  Tip: if you use a Tapi SDK, the `x-api-key` and `x-authorization-token` headers come preconfigured, so you don't have to build them by hand.
</Note>