Keys

Shipwell authenticates your API requests using your company's API keys. If you do not include your key when making an API request or use one that is incorrect or outdated, Shipwell will return an unauthorized error.

Shipwell provides every company with separate keys for testing and for running live transactions. All API requests exist in either production or sandbox, and objects—customers, shipments, quotes, bids, carriers, and so forth—in one mode cannot be manipulated by objects in the other. These environments are completely separated so that you may develop against the latest version without damaging your production data.

Your company's API key can perform any API request to Shipwell, but you can restrict their access with permissions. You can create keys for production and sandbox environments for your company.

Obtaining your API keys

Send an email to support@shipwell.com to set up.

Use only your test API keys for testing and development. This ensures that you don't accidentally modify your live data objects in your supply chain.

If you don't have an administrator or developer role, you may not have access to view your API keys in the Dashboard. Contact your Shipwell's account's owner and ask to be added to their team as a developer.

Production and Sandbox modes

The production and sandbox modes function almost identically, with a few fundamental differences:

• In sandbox mode, external requests and integrations are mocked responses and will not access 3rd party systems or integrations.
• Carriers will not be setup or monitored, transactions with your Financial Management System will not be accessed, and data will not be shared.
• Many of the external integrations will fail to provide actual data (maps, routes, plans, eta updates, and tracking).

Keeping your keys safe

Keep all your API keys secret. API keys should be kept confidential and only stored on your servers.

Use your API key to make any API call on behalf of your company, such as creating charges or performing payments, creating carriers, customers, and shipments that will cause billing, invoicing, and other workflows to execute. Treat your API key as you would any password:

• Grant access only to those who need it.
• Keep the key out of any version control system you may be using.
• Control access to your key using a password manager or secrets management service.
• For greater security, restrict API keys that limit access to and permissions for different areas of your company's supply chain data.

Restrict the permissions of your API Keys

Per security best practice, you may create different API keys to perform certain functions in your company. For example, you might want to create a read_only API key to read tracking and milestone events for your purchase orders and shipments. Additionally, if you would like to create purchase orders from your ERP, you can create an API key that has permission to create purchase orders and does not have permission to do anything else in the system.