> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview, OAuth Authentication, and IP Allowlist

> Authenticate to Lead's REST APIs with OAuth2, choose the right access token scopes, and configure your IP allowlist for production traffic.

<Warning>
  **Upcoming Change**

  OAuth 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](/upcoming-changes#oauth-access-token-caching)
</Warning>

## Introduction

Lead's APIs are [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-based, accept and return JSON-encoded payloads, and use standard HTTP response codes, authentication, and verbs.

## Authentication

Lead uses [OAuth2](https://oauth.net/2/) 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.

<Tip>
  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 <Tooltip tip="time-to-live">TTL</Tooltip>. They can also be limited to certain API scopes which can help you with access control while preventing unauthorized requests.
</Tip>

### Steps

<Steps>
  <Step title="Get Access Token">
    Use your `client_id` and `client_secret` to get an `access_token` with the [Authentication API](/api-reference/endpoint/oauth/get-an-access-token).
  </Step>

  <Step title="Authenticate Requests">
    Use the `access_token` in the `'authorization: Bearer <access_token>'` header to authenticate further API requests.
  </Step>
</Steps>

### Available scopes

Pass one or more of the following values in the `scope` parameter of the [token request](/api-reference/endpoint/oauth/get-an-access-token) (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](/api-integrations/accounts/overview)                       | Read       |
| `account/read_write`            | [Accounts](/api-integrations/accounts/overview)                       | Read/write |
| `account_number/read`           | Account Numbers                                                       | Read       |
| `account_number/read_write`     | Account Numbers                                                       | Read/write |
| `ach/read`                      | [ACH](/api-integrations/ach/overview)                                 | Read       |
| `ach/read_write`                | [ACH](/api-integrations/ach/overview)                                 | Read/write |
| `application/read`              | [Applications](/api-integrations/applications/overview)               | Read       |
| `application/read_write`        | [Applications](/api-integrations/applications/overview)               | Read/write |
| `blockchain_payment/read`       | [Blockchain Payments](/api-integrations/blockchain-payments/overview) | Read       |
| `blockchain_payment/read_write` | [Blockchain Payments](/api-integrations/blockchain-payments/overview) | Read/write |
| `entity/read`                   | [Entities](/api-integrations/entity/overview)                         | Read       |
| `entity/read_write`             | [Entities](/api-integrations/entity/overview)                         | Read/write |
| `event/read`                    | Webhook Events                                                        | Read       |
| `funding/read`                  | Funding                                                               | Read       |
| `funding/read_write`            | Funding                                                               | Read/write |
| `instant_payment/read`          | [Instant Payments](/api-integrations/instant-payments/overview)       | Read       |
| `instant_payment/read_write`    | [Instant Payments](/api-integrations/instant-payments/overview)       | Read/write |
| `internal_transfer/read`        | [Internal Transfers](/api-integrations/internal-transfer/overview)    | Read       |
| `internal_transfer/read_write`  | [Internal Transfers](/api-integrations/internal-transfer/overview)    | 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](/api-integrations/wire/overview)                              | Read       |
| `wire/read_write`               | [Wires](/api-integrations/wire/overview)                              | Read/write |

<Note>
  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.
</Note>

## 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.

```json theme={null}
{
    "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:

<Steps>
  <Step title="Provide Lead With Your IP Subnets">
    Give them to your Technical Account Manager.
  </Step>

  <Step title="Specify Each Subnet">
    Use [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing).
  </Step>
</Steps>

**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).