Handling authentication

Pylon Elements integrate with your existing authentication. When users are logged into your application, they’re automatically logged into Pylon-no separate login required. Elements use an authorization lease to communicate with the Pylon API. Before building Elements into your app, implement an auth handshake in your backend.

How it works

Create a Contributor

When your authenticated user accesses Elements, create a Contributor record in Pylon’s system with the user’s name and email.

Request authorization lease

When the user wants to use Elements, your backend requests a new authorization lease for the user’s Contributor.

Return lease to frontend

Your backend receives the authorization lease from Pylon and passes it to the Elements component.

Element loads

The Element uses the lease to securely communicate with the Pylon API.

This is a one-time setup. Once configured, all Elements in your application will use the same auth handshake.

Prerequisites

Before setting up authentication, ensure you can authenticate with the Pylon API using OAuth 2.0 Client Credentials.

Implementation steps

Step 1: Create a new route

Create an endpoint on your backend (we’ll use /auth/pylon as an example). This route should:

Return 401 unless accessed by a logged-in user
Gather information about the logged-in user
Get an authorization lease from the Pylon API
Return the lease for use in Elements

Step 2: Gather user information

In your backend route handler, collect the following from your logged-in user:

User info	Why we need it
`firstName` and `lastName`	We need to know who this user is to contact them throughout the mortgage process
`email`	We need to contact this user throughout various steps of the mortgage process

Step 3: Create or retrieve Contributor

Use the Pylon API’s contributor { createContributor } mutation to create or retrieve a Contributor record:

mutation CreatePylonContributor($input: CreateContributorInput!) {
  contributor {
    createContributor(input: $input) {
      contributor { id }
    }
  }
}

Variables:

{
  "input": {
    "role": "BORROWER",
    "contactInfo": {
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

Response:

{
  "data": {
    "contributor": {
      "createContributor": {
        "contributor": {
          "id": "cont_123ABC456EXAMPLE"
        }
      }
    }
  }
}

Save the contributorId in your database for future reference. You’ll need it to create leases.

Step 4: Create authorization lease

Use the contributor { createLease } mutation with the contributorId:

mutation CreatePylonLease($input: ContributorCreateLeaseInput!) {
  contributor {
    createLease(input: $input) {
      lease {
        id
        apiUrl
      }
    }
  }
}

Variables:

{
  "input": {
    "contributorId": "cont_123ABC456EXAMPLE"
  }
}

Response:

{
  "data": {
    "contributor": {
      "createLease": {
        "lease": {
          "id": "leas_ZXCV1234ASEXAMPLE",
          "apiUrl": "https://pylon.mortgage"
        }
      }
    }
  }
}

Return the entire lease object to your frontend. Modifying or filtering the object may cause Elements not to load successfully.

Example implementation

Nest.js example

src/auth/pylon.service.ts

async createPylonContributor(user: User) {
  const input = {
    role: "BORROWER",
    contactInfo: {
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
    },
  };

  const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${this.oauthToken}`,
  };

  const response = await axios.post(
    "https://pylon.mortgage/graphql",
    {
      query: `
      mutation CreatePylonContributor($input: CreateContributorInput!) {
        contributor {
          createContributor(input: $input) {
            contributor { id }
          }
        }
      }`,
      variables: { input },
    },
    { headers }
  );

  const pylonContributorId =
    response.data.contributor.createContributor.contributor.id;

  user.pylonContributorId = pylonContributorId;
  await this.usersDatabase.save(user);

  return pylonContributorId;
}

src/auth/pylon.controller.ts

@Post('/auth/pylon')
@UseGuards(LoggedIn) // Only accessible to logged in users
async pylonHandshake(@CurrentUser() user: User) {
  // Get contributor ID (existing or create new)
  const contributorId = user.pylonContributorId ||
    (await this.service.createPylonContributor(user));

  const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${this.oauthToken}`,
  };

  // Request to create lease
  const response = await axios.post(
    "https://pylon.mortgage/graphql",
    {
      query: `
      mutation CreatePylonLease($input: ContributorCreateLeaseInput!) {
        contributor {
          createLease(input: $input) {
            lease { id apiUrl }
          }
        }
      }`,
      variables: {
        input: { contributorId }
      },
    },
    { headers }
  );

  const lease = response.data.contributor.createLease.lease;

  return lease;
}

Implement logout

When a user logs out of your platform, destroy the Pylon session:

import { useSession } from "@pylonlending/react-elements";

const App = () => {
  const { destroy } = useSession();

  const onLogout = () => {
    // Your logout logic
    destroy(); // Destroy Pylon session
  };

  return (
    // Your app components
  );
};

Content Security Policy (CSP)

If you’re using a Content Security Policy, add these directives:

default-src https://api.{customer-id}.{env}.pylon.mortgage
frame-src https://api.{customer-id}.{env}.pylon.mortgage
script-src https://api.{customer-id}.{env}.pylon.mortgage/elements/pylon.js
connect-src https://api.{customer-id}.{env}.pylon.mortgage

Replace {customer-id} with your customer ID and {env} with test or prod.

Next steps

With authentication configured, you can now build Elements into your app:

Loan Application Element - Start here for new applications
Borrower Dashboard Element - For managing existing loans

GET STARTED

EXAMPLES

ELEMENTS

CORE ENTITIES

How it works

Prerequisites

Implementation steps

Step 1: Create a new route

Step 2: Gather user information

Step 3: Create or retrieve Contributor

Step 4: Create authorization lease

Example implementation

Nest.js example

Implement logout

Content Security Policy (CSP)

Next steps

​How it works

​Prerequisites

​Implementation steps

​Step 1: Create a new route

​Step 2: Gather user information

​Step 3: Create or retrieve Contributor

​Step 4: Create authorization lease

​Example implementation

​Nest.js example

​Implement logout

​Content Security Policy (CSP)

​Next steps

How it works

Prerequisites

Implementation steps

Step 1: Create a new route

Step 2: Gather user information

Step 3: Create or retrieve Contributor

Step 4: Create authorization lease

Example implementation

Nest.js example

Implement logout

Content Security Policy (CSP)

Next steps