Role-Based API Access

Complexity:    

Audience: Upper Management, Developers, Loan Servicing/Collections Managers, Administrator, Data

Introduction

Many LoanPro users have teams of personnel with varying levels of knowledge and authority. As such, we created Agent User Roles to allow you to grant access to specific areas of the software to each of your personnel. This kind of access configuration now extends to API use.

In the past, each tenant was assigned only one API user and only one token. If you needed multiple personnel within your company to use the API, you ran into an issue: every user with the tenant's credentials had full access to every request, and there was no way to limit their capabilities. This posed a risk to the security and integrity of the data within your account.

However, those days are no more, as we’ve updated the way API keys are handled by the software. Now, each agent user within your team can be granted API access individually, and you can limit what kinds of requests each user can send. In this article, we'll explain how to use the API access settings and cover some commonly asked questions.

How Role-Based API Access Works

Role-Based API Access gives you control over which users have access to the API with the combined usage of API Keys, agent users, and user roles. Agent users—profiles for your personnel within the software—are assigned a role, which is a configured set of access to specific parts of the software. Your existing agent users and roles are used to grant API access, but since it's likely that not all of your personnel will use the API, access to features in the UI and the API are kept separate. This makes it easier to keep all of your access settings straight.

You determine the access a role has by using the resource tree—a long, expandable list of locations and actions available within the software. You've probably seen the resource tree used for the UI access when creating user roles. Access to the API, however, uses a separate resource tree, and it grants users access to specific endpoints and methods. For example, if you want to grant specific users access to GET requests only, the API resource tree will allow you to do so.

When you want to grant a member of your team access to the API, you create a new API user by selecting their existing agent user profile (we'll show you how to do this below). When this happens, the agent user is given an individual API token. This token is used to authenticate the user's API requests, and the token can be manually renewed at any time. To ensure smooth token rotation, each user is allowed up to two active tokens. Then, when the user sends an API request, their key is authenticated by the system, and their role is checked to determine whether they have access to the type of request they're making. Here's a simplified flowchart of all of this entire process:

  1. You create an agent user.
  2. You create a user role that determines access to specific parts of the UI and API. Then, you assign the role to your agent user.
  3. You create an API key for your agent user.
  4. Your agent user attempts to send an API request using their key, and their role is checked to determine whether they have access to make the request.
  5. If their key is valid and their role allows it, the API request is sent.

Below, we'll explain how to grant and revoke API access. However, we're going to skip over creating agent users. If you need some guidance on doing so, our linked articles above will help you out.

Determining API Access via Roles

If you've ever used roles, you'll know they make it easy to create access configurations for your personnel. Before creating API tokens for your users, you will want to start by determining API access to a new or existing role. To grant API access to a role, navigate to Settings > Company > Access > Roles.

Next, click 'Add New Role' in the top right corner or click the edit icon to update an existing role. On the first screen, you will input the role's name and description, and determine whether this role can view customers' bank account and social security information. Make sure to choose a name and description that will help you differentiate this role from others. In our example, we're creating a role that grants access only to GET requests.

On the second screen, you will determine the UI access that will be granted to this role. The access granted to the UI uses the resource tree that you may be familiar with already. Since the list of available options is quite long, you can both search and expand the tree to view the list at a more granular level. Once you've determined UI access, click 'Next' to navigate to the next set of options.

The third screen includes the API resource tree. Here, you determine which endpoints and methods can be used in API requests sent by users assigned to the role. Make sure to expand each endpoint if you'd like to grant this role access to only specific methods.

How existing roles are affected by the changes to API access
User-specific API access is a new feature, and it will affect the existing roles within your account. All existing roles within your account—including the global roles—will be automatically granted full API access, meaning all endpoint and methods will be available to all users. Make sure to edit each role's access if you'd prefer to limit its API access.
Searches made with the API are sent via a POST request. Therefore, if you'd prefer not to allow API users access to completing searches for loans or customers, you will have to disable POST requests for those endpoints entirely. In other words, if a user can create loans and customers, they can also search for them and vice versa. There is currently no way to solely limit users from completing searches.

Creating New API Keys for Agents

Before creating an API agent user for a member of your team, they must first have an existing UI agent user profile. Once that's complete, you can create an API agent user by navigating to Settings > Company > API > Overview. This is the hub for the API settings associated with your tenant. Here, you’ll be able to view your API URL, tenant ID, and the users who have API access. By clicking ‘New API Key’ in the top right, you can create a new API user.

Next, a window will appear and allow you to select one of the existing agents within your account. Using the drop-down menu, select the agent that will be granted API access and click ‘Create API Key’. At this point, the system will check to see if the chosen agent has an existing set of API keys. If so, an error message will appear. If not, a user will be successfully activated.

If you'd like to grant a user a second key, simply follow the same process above and add the user again.

Once you have created API agents, they will appear on the API Overview page. Each agent will have the following information displayed:

Information

Description

API Token

This is the authentication token associated with the API agent. This will be used in the headers of API requests to validate the user.

Name

This is the name of the agent who now has API access.

Role

This is the role assigned to the agent. Roles are created within your account, and they determine how far the agent's API capabilities extend. The access that each role grants is up to you.

Status

This is the status of the agent. Each agent's access can be instantly turned on or off by clicking the button located within this column.

This page also allows you to inactive, rotate, and delete API keys. Keys can be inactivated by selecting the green sliding button. Inactivating a key allows you to revoke a user's access temporarily. If desired, you can also rotate keys at any time by clicking the rotate icon located on the right side of the agent user's information. If you'd like to delete an API key entirely, click the trash icon.

At this point, your agent user can now start sending request to LoanPro's API.

Common Uses & Questions

Lenders with large teams of personnel likely have multiple employees who need API access. It's common to see these lenders distribute keys out to their teams to track which users are sending which requests. Lenders who have built integrations with LoanPro also tend to create API keys to track their system's API usage.

Is there a limit to how many API keys I can have active at a time? Nope, there is no limit. You can create as many as you'd like, but we wouldn't recommend creating them without good reason: More keys equals more risk. And if you'd like to rotate keys frequently, rotating a lot of keys can get tedious.

After I create API users, will they be able to view their token information? By default, only the Tenant Admin role will have access to the API Overview page, meaning all agent users who aren't assigned the Tenant Admin role will not be able to view their own (and other users') token information. As the admin, you will need to distribute token information out to your agent users yourself. If you prefer, you could grant other roles access to the API Overview page, but we don't recommend doing so.

Since Role-Based API Access focuses heavily on the access that you provide your personnel, we recommend looking into the articles in our Access category. Here, you'll learn how to set up IP Restrictions, Multi-Factor Authentication, and more. If you'd like a bit more information about our agent users functionality, we also recommend taking a look at the Agent Users category. Lastly, we have a wealth of information regarding our API. API Basics will help you get started with using the API, and our ReadMe site lists all of our requests with interactive payloads.

What’s Next

This is the end of our documentation on creating user-based API settings for your account, but we recommend diving into the related topics if you'd like to continue learning.


How did we do?


Powered by HelpDocs (opens in a new tab)