Create and Manage Postsale API Keys
Connect your own systems to the Postsale API
In This Article
Use Application Programming Interface (API) keys to connect your own systems to the Postsale API. Each key can use only the Shipment API and Order API permissions that you select.
This article guides you through:
- Creating a Postsale API key with the permissions your integration needs
- Enabling, disabling, editing, regenerating, reviewing, and revoking an existing API key
Before You Begin
- Visit developer.postsale.com for Postsale's API technical reference documentation
- Creating and using API Keys is a premium feature requiring a Soar billing plan. Learn more about managing your Postsale account in our Frequently Asked Questions.
Here are a few suggestions to help you get started with your Postsale API keys:
- Create a separate API key for each integration so you can assign only the permissions it needs and manage the key without affecting other integrations.
- Decide which Shipment API and Order API permissions your integration requires
- A list of the available permissions is provided for you below
- For added security:
- Grant read-only access wherever possible and avoid permissions the integration does not need
- Treat every API key like a password because the key acts on your Postsale account
- Prepare a secure password manager or secret manager where you can store the API key
- Postsale API keys are shown only once upon creation. Be sure to save your key(s) for later access if needed.
Create a New API Key
Follow the steps in this section to create a new Postsale API key.
Real-World Example
We would like to connect our internal order management system to Postsale. We would like to create an API key with only the permissions our system needs.
- Open the Settings menu, and select Account Settings.
- In the left-hand sidebar, select Integrations.
- On the Integrations page, select API Keys.
- In the API Keys pop-up, select Add.
- Enter a descriptive name in the Name field.
We suggest naming the key after the system or purpose that will use it, so you can identify it later.
- Expand each API section and select only the permissions the integration needs.
A detailed list of available permissions and their descriptions is provided in the Good to Know section below.
- Select Make Read-Only when the integration only needs to retrieve information from Postsale.
Make Read-Only selects the available read permissions and clears permissions that create, edit, delete, purchase, schedule, or otherwise change information.
Write permissions have been automatically removed.
- Decide whether to enable Record request and response bodies, then click Create.
- Recording response bodies is useful when getting your integration working and for troubleshooting. Requests will be listed either way, but enabling this setting stores what was sent and what was returned in the requests.
- Postsale removes names, addresses, contact details, and identifiers before storing the body, retaining only fields known to be safe. A stored body is still a copy of a real request, so turn logging off when you finish debugging. Postsale deletes recorded bodies after a short retention period and displays them with the key's activity.
The key is created and displayed for you in the New API Key pop-up.
- Click Copy to copy the API key and store the key securely.
Copy the API Key Now
Postsale displays the API key only once. Copy and securely store it before you close the pop-up because Postsale will not show it again.
- Click Done to return to the list of API keys.
Postsale adds the key to the API Keys pop-up and displays its permissions, creation date, usage status, logging status, and management actions.
Manage Existing API Keys
Manage your API key(s) from the API Keys pop-up. You can temporarily disable a key, edit its permissions, regenerate its secret, review its activity, or revoke it.
Real-World Example
We would like to manage our Order Management System API key. We need to edit the permissions and regenerate a new key for security reasons. We'd also like to explore the other options available.
- Go to Settings > Account Settings > Integrations, select API Keys, and locate the key you wish to manage.
Each key includes an Enabled toggle and the following actions:- Enable or disable the API key
- Edit Permissions
- Regenerate
- View Activity
- Revoke the API key
- Use the Enable/Disable toggle to disable or enable the key.
A disabled key remains in Postsale but refuses API requests until you enable it again.
- Select Edit Permissions to update the Shipment API and Order API permissions. Click Save.
- You can change permissions without replacing the key.
- Removing a permission causes Postsale to refuse requests that need that permission and may break a running integration.
- Select Regenerate to generate a new API Key. Review the confirmation, and select Regenerate again.
Be sure to copy and save the new API Key in a secure location for future reference.
Regeneration Replaces the Secret
Regenerating issues a new secret and immediately disables the current secret. The key keeps its name, permissions, and activity history, but anything that still uses the previous secret will fail until you update it.
- Select Activity to review the key's requests and request or response bodies retained for debugging.
- The activity screen lists every request. Use the Record request and response bodies toggle to control whether Postsale retains the sent and returned bodies with each request.
- The activity screen lists every request. Use the Record request and response bodies toggle to control whether Postsale retains the sent and returned bodies with each request.
- Select Revoke to permanently remove the API key. Review the confirmation, and select Revoke again.
Revoking an API Key Cannot Be Undone
Revoking a key permanently stops it from working. Anything that uses the key will fail, and you cannot restore the revoked key.
Good To Know
- Send an API key as a bearer token in the Authorization header
- API keys cannot access billing or account-security endpoints
- API keys cannot access templates or automations
- The API Keys pop-up shows each key's selected permissions, creation date, usage status, and logging status
- Disable a key when you need a reversible pause, and revoke it only when you wish to remove its access permanently
Available Permissions
Select the appropriate tab to view a list of available permissions and their descriptions.
Shipment API
Shipments
- Read Shipments: Look up and search shipments.
- Get Rate Quotes: Compare carrier rates for a shipment. Costs the account nothing.
- Create Shipments: Add new shipments, with their packages and addresses.
- Edit Shipments: Change existing shipments, including adding and removing packages.
- Delete Shipments: Remove shipments. They stop being reachable, and this cannot be undone.
Labels
- Read Labels: Retrieve labels and their tracking details.
- Buy Labels: Purchase postage. Spends money against the account payment method.
- Void Labels: Cancel a purchased label and request a refund.
Carriers
- Read Carriers: See connected carrier accounts, their settings, and carrier drop-off locations.
- Manage Carriers: Connect, edit, and disconnect carrier accounts. Disconnecting one stops every future shipment on it.
Pickups
- Check Pickup Availability: Ask a carrier when it could collect. Currently FedEx only.
- Schedule Pickups: Book a carrier collection. This sends a courier to the address.
- Cancel Pickups: Cancel a booked collection.
Manifests
- Read Manifests: See end-of-day manifests and which shipments are eligible for one.
- Create Manifests: Close out the day by submitting a manifest to the carrier.
Addresses
- Read Addresses: See saved ship-from addresses, and look up or autocomplete an address.
- Manage Addresses: Add, edit, and remove ship-from addresses.
Shipping Rules
- Read Shipping Rules: See the rules that pick a service and packaging, and what they would do for a shipment.
- Manage Shipping Rules: Create, edit, and delete shipping rules.
Documents
- Read Documents: Retrieve customs paperwork and commercial invoices attached to a shipment.
- Manage Documents: Upload, replace, and remove customs documents.
Shipping Settings
- Read Shipping Settings: See account-level shipping settings.
- Manage Shipping Settings: Change account-level shipping settings.
Insurance
- Read Insurance Claims: See claims filed against a shipment.
Order API
Orders
- Read Orders: Look up and search orders.
- Create Orders: Add new orders, including reading one out of pasted text or a photographed packing slip.
- Edit Orders: Change existing orders, including setting their status and applying tags.
- Delete Orders: Remove orders, and restore ones already removed, the only way back from a deletion.
Order Setup
- Read Statuses, Tags and Filters: See the custom order statuses, tags, item attributes and filters this account defines.
- Manage Statuses, Tags, and Filters: Create, edit, and delete custom order statuses, tags, item attributes, and filters.
Stores
- Read Stores: See connected stores, what each supports, and the history of orders imported into them.
- Manage Stores: Connect, edit, and disconnect stores, and run imports. Disconnecting a store stops orders arriving from it. Importing needs the order create and edit permissions too.
Reports
- Read Reports: Run revenue, shipment, and item reports, and review the dashboard layout.
- Arrange the Dashboard: Save and reset which widgets the dashboard shows. Nothing here changes a report’s data.