{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["img"]},"type":"markdown"},"seo":{"title":"Authentication","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication","__idx":0},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains how to authenticate when using the EasyPost Connect API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The EasyPost Connect API is secured through three authentication layers:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mutual TLS (mTLS)"]}," at the domain level"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API key"]}," provided in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," request header"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bearer token"]}," obtained through the OAuth 2.0 Client Credentials flow"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All three layers are required when calling protected API endpoints."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The setup can be completed in the EasyPost Connect Portal. Log in, open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Services"]}," menu, and select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integration Pack"]},"."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/publicapisetup.3e1e05d6877382e66e64a20609febc40acf8e979918192317b68cc78f948bc6c.9c1bb791.png","alt":"Platform API Setup Screen","withLightbox":true,"width":"","height":""},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mutual-tls-mtls-setup","__idx":1},"children":["Mutual TLS (mTLS) Setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All calls to the EasyPost Connect API must use mutual TLS."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["mTLS requires your system to authenticate itself with a client certificate when connecting to the API domain."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1---generate-a-private-key","__idx":2},"children":["Step 1 - Generate a Private Key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run the following command to create a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2048-bit RSA private key"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"openssl genrsa -out client.key 2048\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The generated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.key"]}," file is your private key. Keep it secure and never share it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2---generate-a-certificate-signing-request-csr","__idx":3},"children":["Step 2 - Generate a Certificate Signing Request (CSR)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a CSR using the private key:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"openssl req -new -key client.key -out client.csr -subj \"/CN=client.example.com\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Item"},"children":["Item"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.csr"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CSR file to upload in the EasyPost Connect Portal."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-subj"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Certificate subject. Customize the Common Name (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CN"]},") to match your application or client name."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3---request-and-store-your-client-certificate","__idx":4},"children":["Step 3 - Request and Store Your Client Certificate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To request your client certificate:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log in to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://eservices.easypost.eu"},"children":["EasyPost Connect Portal"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Services"]}," menu."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integration Pack"]}," card."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connect API"]}," tab."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Paste the contents of your Certificate Signing Request ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.csr"]}," file into the certificate request field (text input area located on the left)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Download the signed (generated) client certificate, provided as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.crt"]}," in PEM format."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the signed certificate securely together with the private key."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mtls-best-practices","__idx":5},"children":["mTLS Best Practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep the private key secure and never share it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store private keys and certificates in a secure vault, such as AWS Secrets Manager, Azure Key Vault, Google Secret Manager, or HashiCorp Vault."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-key-generation","__idx":6},"children":["API Key Generation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API key is generated on the right-hand panel of the Public API setup screen in the EasyPost Connect Platform."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/client_credentials_key.f643e809743edff7813745c5d5ac8fff1e226b2ff42f7c3387f1774f1dbbcc81.9c1bb791.png","alt":"Platform API Setup - Generation of Credentials","withLightbox":true,"width":"","height":""},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API key is issued together with the OAuth 2.0 client credentials:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API key must be sent in every API request using the following header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"x-api-key: <your_generated_api_key>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"oauth-20-credentials","__idx":7},"children":["OAuth 2.0 Credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," generated in the setup screen are used to obtain a Bearer token."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Bearer token must be sent in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header of every API request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["EasyPost Connect uses the OAuth 2.0 Client Credentials flow."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"oauth-20-token-domains","__idx":8},"children":["OAuth 2.0 Token Domains"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the correct OAuth 2.0 domain for your environment:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"OAuth 2.0 domain"},"children":["OAuth 2.0 domain"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACC"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth.acc.eservices.easypost.eu"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PRO"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth.eservices.easypost.eu"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The token endpoint is:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"https://<oauth2_domain>/oauth2/token\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-an-access-token","__idx":9},"children":["Request an Access Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," endpoint of the relevant authentication domain."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["curl"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n  \"https://${OAUTH2_DOMAIN}/oauth2/token\" \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=client_credentials\" \\\n  -d \"client_id=YOUR_GENERATED_CLIENT_ID\" \\\n  -d \"client_secret=YOUR_GENERATED_CLIENT_SECRET\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type=client_credentials"]}," parameter indicates that the OAuth 2.0 Client Credentials flow is used."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the credentials are valid, the response contains an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"access_token\": \"eyJraWQiOiJ...\",\n  \"expires_in\": 3600,\n  \"token_type\": \"Bearer\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," as a Bearer token when calling the API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"performing-an-authenticated-api-call-to-supported-endpoints","__idx":10},"children":["Performing an Authenticated API Call to Supported Endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To call the EasyPost Connect Public API, your request must:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use mTLS with your client certificate and private key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include the OAuth 2.0 Bearer token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include the API key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["curl"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \\\n  \"https://api.eservices.easypost.eu/jobs\" \\\n  --cert \"<client_certificate>\" \\\n  --key \"<client_key>\" \\\n  -H \"Authorization: Bearer eyJraWQiOiJ...\" \\\n  -H \"x-api-key: <your_generated_api_key>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":11},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every authenticated API request requires:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Requirement"},"children":["Requirement"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Where it is used"},"children":["Where it is used"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client certificate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["mTLS connection"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client private key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["mTLS connection"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OAuth 2.0 access token"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <token>"]}," header"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If one of these elements is missing or invalid, the API request will be rejected."]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"Mutual TLS (mTLS) Setup","id":"mutual-tls-mtls-setup","depth":2},{"value":"Step 1 - Generate a Private Key","id":"step-1---generate-a-private-key","depth":3},{"value":"Step 2 - Generate a Certificate Signing Request (CSR)","id":"step-2---generate-a-certificate-signing-request-csr","depth":3},{"value":"Step 3 - Request and Store Your Client Certificate","id":"step-3---request-and-store-your-client-certificate","depth":3},{"value":"mTLS Best Practices","id":"mtls-best-practices","depth":3},{"value":"API Key Generation","id":"api-key-generation","depth":2},{"value":"OAuth 2.0 Credentials","id":"oauth-20-credentials","depth":2},{"value":"OAuth 2.0 Token Domains","id":"oauth-20-token-domains","depth":3},{"value":"Request an Access Token","id":"request-an-access-token","depth":3},{"value":"Performing an Authenticated API Call to Supported Endpoints","id":"performing-an-authenticated-api-call-to-supported-endpoints","depth":2},{"value":"Summary","id":"summary","depth":2}],"frontmatter":{"seo":{"title":"Authentication"}},"lastModified":"2026-06-11T12:18:59.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}