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

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.

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

openssl genrsa -out client.key 2048

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

Create a CSR using the private key:

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

Where:

To request your client certificate:

1. Log in to the EasyPost Connect Portal.
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 Reuqest 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.

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

The API Key is generated on the right panel of the Public API setup in the EasyPost Connect Platform.

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:

x-api-key: <your_generated_api_key>

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.

Use the correct OAuth 2.0 domain for your environment:

The token endpoint is:

https://<oauth2_domain>/oauth2/token

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

Example using curl:

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:

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

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

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:

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>"

Every authenticated API request requires:

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