# Authentication

This guide explains how to authenticate when using the EasyPost Connect API.

The EasyPost Connect API is secured through three authentication layers:

* **Mutual TLS (mTLS)** at the domain level
* An **API key** provided in the `x-api-key` request header
* A **Bearer token** obtained through the OAuth 2.0 Client Credentials flow


All three layers are required when calling protected API endpoints.

The setup can be completed in the EasyPost Connect Portal. Log in, open the **Services** menu, and select **Integration Pack**.

Platform API Setup Screen
## Mutual TLS (mTLS) Setup

All calls to the EasyPost Connect API must use mutual TLS.

mTLS requires your system to authenticate itself with a client certificate when connecting to the API domain.

### Step 1 - Generate a Private Key

Run the following command to create a **2048-bit RSA private key**:

```bash
openssl genrsa -out client.key 2048
```

The generated `client.key` file is your private key. Keep it secure and never share it.

### Step 2 - Generate a Certificate Signing Request (CSR)

Create a CSR using the private key:

```bash
openssl req -new -key client.key -out client.csr -subj "/CN=client.example.com"
```

Where:

| Item | Description |
|  --- | --- |
| `client.csr` | CSR file to upload in the EasyPost Connect Portal. |
| `-subj` | Certificate subject. Customize the Common Name (`CN`) to match your application or client name. |


### Step 3 - Request and Store Your Client Certificate

To request your client certificate:

1. Log in to the [EasyPost Connect Portal](https://eservices.easypost.eu).
2. Open the **Services** menu.
3. Select the **Integration Pack** card.
4. Open the **Connect API** tab.
5. Paste the contents of your Certificate Signing Request `client.csr` file into the certificate request field (text input area located on the left).
6. Submit the request.
7. Download the signed (generated) client certificate, provided as `client.crt` in PEM format.


Store the signed certificate securely together with the private key.

### mTLS Best Practices

- Keep the private key secure and never share it.
- Store private keys and certificates in a secure vault, such as AWS Secrets Manager, Azure Key Vault, Google Secret Manager, or HashiCorp Vault.


## API Key Generation

The API key is generated on the right-hand panel of the Public API setup screen in the EasyPost Connect Platform.

Platform API Setup - Generation of Credentials
The API key is issued together with the OAuth 2.0 client credentials:

- `client_id`
- `client_secret`


The API key must be sent in every API request using the following header:

```http
x-api-key: <your_generated_api_key>
```

## OAuth 2.0 Credentials

The `client_id` and `client_secret` generated in the setup screen are used to obtain a Bearer token.

The Bearer token must be sent in the `Authorization` header of every API request.

EasyPost Connect uses the OAuth 2.0 Client Credentials flow.

### OAuth 2.0 Token Domains

Use the correct OAuth 2.0 domain for your environment:

| Environment | OAuth 2.0 domain |
|  --- | --- |
| `ACC` | `auth.acc.eservices.easypost.eu` |
| `PRO` | `auth.eservices.easypost.eu` |


The token endpoint is:

```text
https://<oauth2_domain>/oauth2/token
```

### Request an Access Token

Use the `/oauth2/token` endpoint of the relevant authentication domain.

Example using `curl`:

```bash
curl -X POST \
  "https://${OAUTH2_DOMAIN}/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_GENERATED_CLIENT_ID" \
  -d "client_secret=YOUR_GENERATED_CLIENT_SECRET"
```

The `grant_type=client_credentials` parameter indicates that the OAuth 2.0 Client Credentials flow is used.

If the credentials are valid, the response contains an `access_token`:

```json
{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

Use the returned `access_token` as a Bearer token when calling the API.

## Performing an Authenticated API Call to Supported Endpoints

To call the EasyPost Connect Public API, your request must:

1. Use mTLS with your client certificate and private key.
2. Include the OAuth 2.0 Bearer token in the `Authorization` header.
3. Include the API key in the `x-api-key` header.


Example using `curl`:

```bash
curl -X GET \
  "https://api.eservices.easypost.eu/jobs" \
  --cert "<client_certificate>" \
  --key "<client_key>" \
  -H "Authorization: Bearer eyJraWQiOiJ..." \
  -H "x-api-key: <your_generated_api_key>"
```

## Summary

Every authenticated API request requires:

| Requirement | Where it is used |
|  --- | --- |
| Client certificate | mTLS connection |
| Client private key | mTLS connection |
| API key | `x-api-key` header |
| OAuth 2.0 access token | `Authorization: Bearer <token>` header |


If one of these elements is missing or invalid, the API request will be rejected.