Skip to main content
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

1

Create a Contributor

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

Request authorization lease

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

Return lease to frontend

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

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 infoWhy we need it
firstName and lastNameWe need to know who this user is to contact them throughout the mortgage process
emailWe 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": "[email protected]",
      "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: CreateLeaseInput!) {
  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: CreateLeaseInput!) {
        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: