Overview

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`

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

Obtaining an access token

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

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"
  }'

Replace audience with https://sandbox.pylon.mortgage when authenticating against the sandbox environment.

Response

A successful authentication request returns:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Your access token expires after 24 hours. Cache and reuse your token until it expires to minimize authentication overhead.

Using your access token

Include your access token as a Bearer token in the Authorization header for all API requests:

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

Acting on behalf of a user

A machine credential has no user of its own, so by default every write it makes is attributed to your integration. To attribute an action to a specific person instead, send the x-pylon-on-behalf-of header. This is attribution, not authorization — it records who acted; it never grants access, and your token’s scopes still gate every request.

Header	Value
`x-pylon-on-behalf-of`	A contributor id (`cont_…`) or a borrower id (`borr_…`) to attribute the action to.

Only machine credentials (a client-credentials token with no signed-in user) may send this header.
A borr_… value attributes to that borrower’s delegated contributor, created automatically on first use.
Omit the header to attribute the action to your integration.

Today this header sets the uploader on document uploads. See Contributors for how attribution works and where it surfaces.

curl -X POST "https://pylon.mortgage/api/loans/${LOAN_ID}/documents/underwriting" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "x-pylon-on-behalf-of: cont_123ABC456EXAMPLE" \
  --form "document-files=@statement.pdf"

The request is rejected with 400 if the header is sent more than once, carries anything other than a single cont_… or borr_… id, or is sent by a non-machine credential.

Authentication flow

The OAuth 2.0 Client Credentials flow works as follows:

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

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

Environments

Obtaining an access token

Response

Using your access token

Acting on behalf of a user

Authentication flow

Error handling

​Environments

​Obtaining an access token

​Response

​Using your access token

​Acting on behalf of a user

​Authentication flow

​Error handling

Environments

Obtaining an access token

Response

Using your access token

Acting on behalf of a user

Authentication flow

Error handling