API Overview, OAuth Authentication, and IP Allowlist

Upcoming ChangeOAuth access tokens will be cached for up to 23 hours and must be reused until expiration. Partners requesting a new token before every API call will need to update their authentication implementation before enforcement begins.👉 View Details

Introduction

Lead’s APIs are REST-based, accept and return JSON-encoded payloads, and use standard HTTP response codes, authentication, and verbs.

Authentication

Lead uses OAuth2 for Authentication. When we onboard your program, you will be set up with a client_id and a client_secret. These credentials can be used to retrieve an access_token which you will use to authenticate further requests.

By default, access tokens have a 24 hour expiry, and will need to be replaced before they expire. See the expires_in passed in the token response to track the . They can also be limited to certain API scopes which can help you with access control while preventing unauthorized requests.

Steps

Get Access Token

Use your client_id and client_secret to get an access_token with the Authentication API.

Authenticate Requests

Use the access_token in the 'authorization: Bearer <access_token>' header to authenticate further API requests.

Available scopes

Pass one or more of the following values in the scope parameter of the token request (space-delimited) to provision an access token. Request the least-privileged scope appropriate to the operation. A token presented to an endpoint that requires a scope it was not provisioned for returns 403.

Scope	Resource	Access
`account/read`	Accounts	Read
`account/read_write`	Accounts	Read/write
`account_number/read`	Account Numbers	Read
`account_number/read_write`	Account Numbers	Read/write
`ach/read`	ACH	Read
`ach/read_write`	ACH	Read/write
`application/read`	Applications	Read
`application/read_write`	Applications	Read/write
`blockchain_payment/read`	Blockchain Payments	Read
`blockchain_payment/read_write`	Blockchain Payments	Read/write
`entity/read`	Entities	Read
`entity/read_write`	Entities	Read/write
`event/read`	Webhook Events	Read
`funding/read`	Funding	Read
`funding/read_write`	Funding	Read/write
`instant_payment/read`	Instant Payments	Read
`instant_payment/read_write`	Instant Payments	Read/write
`internal_transfer/read`	Internal Transfers	Read
`internal_transfer/read_write`	Internal Transfers	Read/write
`lending/read`	Lending	Read
`lending/read_write`	Lending	Read/write
`subledger_balance/read`	Subledger Balances	Read
`subledger_balance/read_write`	Subledger Balances	Read/write
`wire/read`	Wires	Read
`wire/read_write`	Wires	Read/write

There is no separate originator/* scope for the /v0/originators endpoints. If you’re unsure which scope a specific endpoint requires, contact your Technical Account Manager.

IP Allowlist

An IP allowlist restricts API access to a predefined set of approved IPv4 addresses or subnets. Requests originating from addresses outside the allowlist are rejected. This provides an additional layer of protection by ensuring that only trusted networks can access the API.

Configuration

Each API partner can be configured with a set of allowed IP subnets. When a request is received, the API server validates the request’s source IP address against the configured allowlist:

If the source IP address falls within an allowed subnet, the request is processed.
If the source IP address does not match any allowed subnet, the request is rejected and an error is returned.

{
    "status": 403,
    "code": "source_ip_not_allowed",
    "title": "Requests from this IP address are not permitted for this program.",
    "invalid_parameters": [
        {
            "parameter": "source_ip",
            "reason": "source IP not allowed for program"
        }
    ]
}

Setup

To utilize Lead’s IP allowlist feature:

Provide Lead With Your IP Subnets

Give them to your Technical Account Manager.

Specify Each Subnet

Use CIDR notation.

Configuration limits:

Maximum subnets: 30
Supported IP version: IPv4 only
Supported CIDR prefix lengths: /20 to /32
Broader ranges such as /16 or /8 are not supported.

Unsupported IP Addresses

The following IP address types cannot be included in the IP allowlist. IPv6 addresses

Only IPv4 addresses are supported.

Private IP ranges

10.0.0.0/8
172.16.0.0/12
192.168.0.0/16

Loopback addresses

127.0.0.0/8

Link-local addresses

169.254.0.0/16

Invalid formats

Any address not in valid IPv4 format (x.x.x.x, where each octet is between 0 and 255).

Foundations

API Guides

Introduction

Authentication

Steps

Available scopes

IP Allowlist

Configuration

Setup

Unsupported IP Addresses

​Introduction

​Authentication

​Steps

​Available scopes

​IP Allowlist

​Configuration

​Setup

​Unsupported IP Addresses

Introduction

Authentication

Steps

Available scopes

IP Allowlist

Configuration

Setup

Unsupported IP Addresses