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

# Authentication & Security

> How to authenticate Platform API requests with basic or bearer authentication, and how to use mutual TLS, IP allowlisting, and encrypted responses.

All Platform API requests must use HTTPS with TLS 1.2 or later, or [mutual TLS](#mutual-tls), and must be authenticated.

## Basic authentication

Most endpoints use basic access authentication with your `client_id` and `api_key`. Get these credentials from the [Client Dashboard](https://dashboard.mx.com/).

Set the `Authorization` header to `Basic` followed by the Base64 encoding of `client_id:api_key`:

```text theme={null}
Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}
```

For example, the Base64 encoding of `CLIENT-1234:API-KEY-4567` is `Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3`, so the header is:

```text theme={null}
Authorization: Basic Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3
```

Many HTTP clients encode the credentials for you. For example, curl's `-u client_id:api_key` option sends the same header.

In v20260929, Data Exchange endpoints also require an `MX-3DX-TOKEN` header. See the [Data Exchange overview](/api-reference/platform-api/v20260929/reference/data-exchange).

<Warning>
  Keep your `client_id` and `api_key` secret. Don't put them in client-side code, and don't share them in public repositories or forums. These credentials can grant access to your data.
</Warning>

To avoid revealing private information, some requests that fail authentication return `404 Not Found` instead of `401 Unauthorized`.

## Bearer authentication

A few processor endpoints use bearer authentication instead of your `client_id` and `api_key`:

* Request an account number (`GET /account/account_numbers`)
* Check real-time account balance (`POST /account/check_balance`)
* Read the account balance (`GET /payment_account`)
* Get account owner information (`GET /account/transactions`)

For these endpoints, the processor exchanges an authorization code for an access token, then sends it in the `Authorization` header:

```text theme={null}
Authorization: Bearer ACCESS_TOKEN
```

For the full flow, see the [processor guide](/products/connectivity/instant-account-verification/processor-token/processor-guide).

## Mutual TLS

To use mutual TLS (mutual authentication), securely send MX your PEM-formatted certificate and the name of the trusted certificate authority (CA) that signed it.

If your certificate isn't signed by a trusted CA, you must:

* Provide the full certificate chain (root, intermediate, and leaf) to MX.
* Make sure your system trusts the root and intermediate CAs.

To avoid interruptions, send replacement certificates to MX Support at least 30 days before your current certificate expires.

## IP allowlisting

All requests to MX APIs must come from an IP address on your allowlist, which you configure on the Client Dashboard. Requests from any other IP address return `403 Forbidden`.

IP addresses outside the United States aren't normally permitted, so MX reviews requests to add non-US IP addresses before approving them. If MX has questions or needs more information, MX will contact you by email.

## MX IP address ranges

MX runs multiple data centers for failover and load balancing. Each data center has a range of IP addresses, and any address in these ranges can be active.

The DNS entries for MX API URLs can resolve to any IP address in these ranges, and the address can change at any time. If you allowlist the IP addresses that MX API URLs resolve to, you must allowlist every range:

| CIDR | Range |
| - | - |
| 64.77.254.32/27 | 30 addresses from 64.77.254.33 to 64.77.254.62 |
| 66.43.0.0/22 | 1,022 addresses from 66.43.0.1 to 66.43.3.254 |
| 68.142.151.128/26 | 62 addresses from 68.142.151.129 to 68.142.151.190 |
| 97.75.178.32/27 | 30 addresses from 97.75.178.33 to 97.75.178.62 |
| 146.75.94.131/32 | 1 address 146.75.94.131 |
| 170.178.148.0/22 | 1,022 addresses from 170.178.148.1 to 170.178.151.254 |
| 192.41.25.128/26 | 62 addresses from 192.41.25.129 to 192.41.25.190 |
| 192.41.58.128/26 | 62 addresses from 192.41.58.129 to 192.41.58.190 |

## DDoS protection

MX provides on-demand distributed denial-of-service (DDoS) protection through Akamai's DDoS scrubbing center. During a DDoS attack, MX redirects inbound traffic (requests coming into MX) through Akamai.

Outbound requests (requests MX sends to you or your partners) still come from the IP ranges above. Outbound requests include, but aren't limited to, mobile upstream events, webhooks, and aggregation requests.

If your firewall rules restrict outbound connections to allowlisted IP addresses, add Akamai's addresses to avoid a service disruption during DDoS mitigation. To learn which IP addresses Akamai may use during an attack, and to subscribe to updates, see Akamai's [official documentation](https://techdocs.akamai.com/origin-ip-acl/docs/update-your-origin-server).

## Encrypted responses

The Platform API can encrypt responses in JSON Web Encryption (JWE) format. To receive an encrypted response, include these headers in your request:

| Header | Required | Description |
| :- | :- | :- |
| `Content-Type` | Yes | `application/encrypted.<cipher>+json`, where `<cipher>` is `a256gcm` (recommended) or `a128gcm`. |
| `X-Public-Key` | Yes | Your ECDH public key in Base64-encoded DER format. Supported curves are `secp384r1` (recommended) and `secp256r1` (also known as `prime256v1`). |

No account configuration is needed. If the headers are present and valid, the API encrypts the response. Decrypt the JWE with your private key to get the original response.

If the cipher or public key is invalid, the API returns `412 Precondition Failed` with an unencrypted error message:

| Scenario | Error message |
| :- | :- |
| Invalid public key format | `Invalid public key` |
| Unsupported public key curve | `Unsupported curve: <curve_name>` |
| Invalid cipher | `Unsupported cipher: <cipher_name>` |
| Unknown error | `Error processing parameters` |

<CodeGroup>
  ```bash Request theme={null}
  # Generate an ECDH key pair with a supported curve
  openssl ecparam -name secp384r1 -genkey -noout -out private_key.pem
  openssl ec -in private_key.pem -pubout -outform DER -out public_key.der

  # Base64-encode your public key
  ECDH_PUBLIC_KEY=$(base64 -i public_key.der)

  # Make the API request
  curl -X GET "https://int-api.mx.com/users" \
    -H "Accept: application/json" \
    -H "Accept-Version: v20111101" \
    -H "Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}" \
    -H "Content-Type: application/encrypted.a256gcm+json" \
    -H "X-Public-Key: ${ECDH_PUBLIC_KEY}"
  ```

  ```text 200 Response theme={null}
  eyJhbGciOiJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZHQ00iLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiIuLi4iLCJ5IjoiLi4uIn19.X1mPFDqKVN8wvhKmPj4ZY0oN...
  ```

  ```json 412 Response theme={null}
  { "error": { "message": "Invalid public key" } }
  ```
</CodeGroup>