Lob Authentication: API Keys and Security Best Practices (2026)

Authentication overview

Lob's API utilizes API keys for authenticating requests, granting access to its services for programmatic mail, address verification, and other features. This authentication model is common among RESTful APIs, providing a straightforward method for developers to secure interactions. The API is designed to be stateless, meaning each request must carry its own authentication credentials, typically in the Authorization header.

Lob categorizes API keys into distinct types based on their purpose and environment: publishable and secret keys, each for both test and live environments. This separation allows developers to manage access permissions and test integrations without affecting production data or incurring live costs. For instance, testing address verification or mailpiece creation can be performed in a sandbox environment using test keys before deploying to a live system with live keys. Lob's API reference details the specific authentication requirements for each endpoint.

Supported authentication methods

Lob primarily supports API key authentication for its RESTful API. Additionally, for inbound notifications, Lob utilizes webhook signatures to ensure the integrity and authenticity of received event data.

API Key Authentication

API keys serve as the primary method for authenticating requests to the Lob API. These keys are long, alphanumeric strings that identify and authorize the calling application or user. Lob differentiates between four types of API keys, each serving a specific purpose:

• Publishable Test API Key: Used for client-side testing in the sandbox environment. Generally considered safe to expose in client-side code for development purposes.
• Secret Test API Key: Used for server-side testing in the sandbox environment. These keys should be kept confidential and never exposed in client-side code.
• Publishable Live API Key: Used for client-side operations in the production environment. Similar to its test counterpart, it is generally safe for client-side exposure for specific use cases.
• Secret Live API Key: Used for server-side operations in the production environment. These are highly sensitive credentials and must be kept strictly confidential, never committed to source control or exposed publicly.

When making a request to the Lob API, the appropriate API key is typically included in the Authorization header using HTTP Basic Authentication, with the API key as the username and an empty password. This method is outlined in the Lob API authentication guide.

Webhook Signatures

When Lob sends event data to a developer-defined webhook endpoint, it includes a signature in the X-Lob-Signature header. This signature is generated using a HMAC-SHA256 hash, allowing the receiving application to verify that the webhook payload originated from Lob and has not been tampered with in transit. Verifying webhook signatures is a critical security measure to prevent spoofing and ensure data integrity. The process involves:

1. Retrieving the X-Lob-Signature header.
2. Constructing a string from the timestamp (also in the header) and the raw request body.
3. Hashing this string using your webhook secret and comparing it to the received signature.

Detailed instructions for verifying webhook signatures are provided in the Lob documentation.

The table below summarizes the supported authentication methods:

Getting your credentials

To access Lob's API, you will need to generate API keys from your Lob account dashboard. The process generally involves:

1. Account Creation/Login: If you don't have a Lob account, you'll need to create one. Otherwise, log in to your existing account.
2. Navigate to API Keys: Within the dashboard, look for a section related to 'API Keys' or 'Developers'. The exact path may vary but is typically under settings or a dedicated developer menu.
3. Generate Keys: Lob automatically generates a set of API keys (Publishable Test, Secret Test, Publishable Live, Secret Live) upon account creation or when you access the API keys section for the first time. You can typically regenerate secret keys if they are compromised or for security rotation.
4. Retrieve Webhook Secret: If you plan to use webhooks, you will also need to retrieve your webhook secret. This is usually found within the webhook settings section of your dashboard, associated with specific webhook endpoints you configure.

It's crucial to copy and store your Secret API Keys securely immediately after generation, as they are often only displayed once for security reasons. If lost, you may need to regenerate them, which would invalidate any old keys.

Authenticated request example

Authenticating a request to the Lob API involves including your Secret API Key in the Authorization header using HTTP Basic Authentication. The following example demonstrates a request to the Address Verification API using curl, a common command-line tool for making HTTP requests.

curl -X POST https://api.lob.com/v1/addresses \
  -u <YOUR_SECRET_API_KEY>: \
  -H "Content-Type: application/json" \
  -d '{ "address_line1": "185 Berry Street", "address_city": "San Francisco", "address_state": "CA", "address_zip": "94107" }'

In this example:

• -X POST specifies the HTTP method as POST.
• https://api.lob.com/v1/addresses is the endpoint for creating an address.
• -u <YOUR_SECRET_API_KEY>: sets the Basic Authentication header. Replace <YOUR_SECRET_API_KEY> with your actual Secret Live API Key (for live requests) or Secret Test API Key (for testing). The colon : after the key signifies an empty password, which is Lob's convention for API key authentication.
• -H "Content-Type: application/json" specifies the request body format.
• -d '{ ... }' contains the JSON payload for the address to be created or verified.

For programmatic access in various languages, Lob provides official SDKs (Node.js, Python, Ruby, PHP, Java, Go, C#) that abstract away the raw HTTP request details, making authentication simpler. For instance, in Python, using the Lob SDK:

import lob

lob.api_key = "YOUR_SECRET_API_KEY"

try:
    address = lob.Address.create(
        address_line1='185 Berry Street',
        address_city='San Francisco',
        address_state='CA',
        address_zip='94107'
    )
    print(address)
except lob.LobError as e:
    print(e)

This Python example demonstrates how the SDK handles the underlying authentication mechanism, requiring only that the lob.api_key variable is set with your Secret API Key. The Lob API Reference provides further examples for specific endpoints and SDKs.

Security best practices

Adhering to security best practices is essential when integrating with any API, especially when dealing with sensitive data like addresses and personal information. For Lob's authentication, consider the following:

API Key Management

• Confidentiality of Secret Keys: Never hardcode Secret API Keys directly into client-side code, commit them to public version control systems (like GitHub), or expose them in publicly accessible environments. Store them in secure environment variables, secret management services (e.g., Google Cloud Secret Manager, AWS Secrets Manager), or configuration files that are not publicly exposed.
• Key Rotation: Periodically rotate your Secret API Keys to minimize the impact of a potential compromise. Lob typically supports key regeneration through its dashboard.
• Least Privilege: Use separate API keys for different applications or services where possible, if Lob supports this functionality. This limits the blast radius if one key is compromised.
• Environment Separation: Always use Test API Keys for development and staging environments and Live API Keys only for production. This prevents accidental live transactions during testing.

Webhook Security

• Verify Signatures: Always verify the X-Lob-Signature header in every incoming webhook request. This ensures the request is legitimate and has not been altered. Failure to do so can leave your application vulnerable to spoofed requests.
• Secure Endpoint: Your webhook endpoint should always use HTTPS to encrypt data in transit.
• Idempotency: Design your webhook handler to be idempotent. This means that processing the same event multiple times (due to retries or network issues) should not cause unintended side effects.
• Respond Promptly: Respond to webhook events with an HTTP 2xx status code as quickly as possible. Long processing times can lead to retries from Lob, potentially causing duplicate events.

General Security Measures

• HTTPS Everywhere: All communication with the Lob API should occur over HTTPS to ensure data encryption in transit. Lob's API endpoints are designed to enforce this.
• Error Handling: Implement robust error handling to gracefully manage API failures or authentication errors without exposing sensitive information.
• Audit Logs: Maintain audit logs of API calls and authentication attempts, especially for production environments. This can help detect and investigate suspicious activity.
• Stay Updated: Keep your Lob SDKs and dependencies updated to benefit from the latest security patches and features.