API keys
Last updated
Last updated
Lob authenticates your API requests using your account's API keys. If you do not include your key when making an API request, or use a key that is incorrect or outdated, Lob will return an error with a 401 HTTP response code.
Find all your API Keys in the API Keys tab of your Dashboard Settings.
Log into your Lob account to access your dashboard
Tap on Settings tab located in the bottom left navigation menu.
Tap on the API Keys icon and you'll be able to access both your Live and Test API keys
Your API keys may be manually generated by clicking on the refresh button below each API key. However, this action will invalidate your existing key at the account level and cannot be undone. Only generate new API keys if you have paused your existing integration.
There are two types of API keys: secret and publishable.
Secret keys: Your account's secret API keys can perform any API request to Lob without restriction. These keys should be kept confidential and only stored on your own servers.
Publishable keys: These keys are limited to US verifications, international verifications, and US autocomplete requests. While we encourage you to use a secret key for maximum security, you can publish these keys to JavaScript code or in an Android or iPhone app without exposing print and mail services or your secret key.
Publishable keys are always prefixed with [environment]_pub. Every type comes with a pair of keys: one for the testing environment and one for the live environment.
Every account has a test and a live environment. All API requests are either a test or live request. The two environments are completely separate; data created in the test environment can not access data created in the live environment, and vice versa. You should use the Test Key within the test environment during development to test that your integration is working properly and that your artwork looks as expected. Once you are ready for production, switch to your Live API key.
Use your Test API key to try out the functionality of Lob's service, perform quality assurance, run automated testing, and perform logic that does not require the creation of a mail piece (i.e. previewing campaign audit proofs for approvals) without incurring any charges.
All features that are available in live mode are available in the test environment. When you send a request in test mode, a digital proof and thumbnails will be rendered, but the mail piece will not actually be printed and mailed. PDF proofs and thumbnail images of your mail-pieces are returned in the API response, which is helpful for you to preview the expected print output as well as show previews from your apps. Additionally, a full production-load test can be done in test mode before switching over to production.
Requests made with Test API key always validate request arguments, simulate live environment behavior, and enforce rate limits, but for verification services, will never verify addresses. The US and International verification services trigger behavior with specific argument values, and, if you plan to use these services, we recommend you read the US Verification test environment and International Verification test environment sections.
Test API keys are always prefixed with test_. To send a real mail piece, or verify an address, use your Live API key.
Before going live, you will need to verify your email and add a payment method. A payment method is not required for the first 300 live requests per month to the /v1/us_verifications endpoint (after which you will begin receiving errors with status code 403). A verification email is sent when you create your account and can be requested again through the dashboard.
When you send a live request, your mail piece will be queued for printing and mailing immediately. You will also incur a corresponding charge based on what is printed and mailed. There is no way to undo a live API request, so please use caution when using your Live API key.
Live API keys in production are always prefixed with live_.
Requests made to the API are protected with HTTP Basic authentication. In order to properly authenticate with the API you must use your API key as the username while leaving the password blank. Requests not properly authenticated will return a 401 error code.
For Basic authentication, the authorization request header contains the Base64-encoded username and password, separated by a colon. When handling the request, the server decodes the login details and checks if the user can access the requested content. Since the authorization you pass to Lob does not have a password you will need to Base64-encode “[API_KEY]:”.
