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

# Overview

> Pylon uses OAuth 2.0 Client Credentials to authenticate API requests. This method provides a secure, industry-standard way to access mortgage rate data programmatically.

## Environments

Pylon provides two separate environments, each requiring its own set of credentials:

| Environment    | API URL                          | Auth URL                      |
| -------------- | -------------------------------- | ----------------------------- |
| **Production** | `https://pylon.mortgage`         | `https://auth.pylon.mortgage` |
| **Sandbox**    | `https://sandbox.pylon.mortgage` | `https://auth.pylon.mortgage` |

<Info>
  Contact Pylon to obtain your `client_id` and `client_secret` for each
  environment. Never use sandbox credentials in production or vice versa.
</Info>

***

## Obtaining an access token

Exchange your client credentials for an access token by making a POST request to the auth endpoint:

```bash theme={null}
curl -X POST https://auth.pylon.mortgage/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "${CLIENT_ID}",
    "client_secret": "${CLIENT_SECRET}",
    "audience": "https://pylon.mortgage",
    "grant_type": "client_credentials"
  }'
```

<Warning>
  Replace `audience` with `https://sandbox.pylon.mortgage` when authenticating
  against the sandbox environment.
</Warning>

### Response

A successful authentication request returns:

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}
```

<Warning>
  Your access token expires after **24 hours**. Cache and reuse your token until
  it expires to minimize authentication overhead.
</Warning>

***

## Using your access token

Include your access token as a [Bearer token](https://swagger.io/docs/specification/authentication/bearer-authentication/) in the `Authorization` header for all API requests:

```bash theme={null}
curl -X POST "https://pylon.mortgage/graphql" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{"query": "your query here"}'
```

## Authentication flow

The OAuth 2.0 Client Credentials flow works as follows:

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Auth as auth.pylon.mortgage
    participant API as pylon.mortgage

    Client->>Auth: POST /oauth/token<br/>(client_id, client_secret, audience)
    Auth-->>Client: { access_token, token_type }

    Note over Client: Cache token for up to 24 hours

    Client->>API: POST /graphql<br/>Authorization: Bearer {token}
    API-->>Client: { data: { ... } }
```

## Error handling

| HTTP Status | Error               | Resolution                                                     |
| ----------- | ------------------- | -------------------------------------------------------------- |
| `400`       | Invalid request     | Check your request body format and required fields             |
| `401`       | Invalid credentials | Verify your `client_id` and `client_secret`                    |
| `403`       | Forbidden           | Confirm your credentials have access to the target environment |