Authentication & keys
Contents 26 pages
Every request carries an API key as a bearer token:
Authorization: Bearer se_live_7qk3m2a9_TFhCS0JnLTBqVFlvNGZfMV81dGhrRWFxV0k3ekYzVXM_3k7m2qThere are no cookies, no sessions, and no CSRF token. The key is the whole credential — treat it like a password.
A Shopify store makes its keys in its Shopify app, under AI & API in the app's menu, and they act for the store alone. See Shopify stores.
The token#
se_live_7qk3m2a9_<43 characters>_<6 characters>
│ │ │ │ └─ checksum
│ │ │ └─ the secret: 32 random bytes, base64url
│ │ └─ the key id: public, and the half we can show you
│ └─ mode: live or test
└─ vendor prefixTwo halves matter to you:
The key id (
7qk3m2a9) is public. It appears in the web app and in support conversations. Quote it freely.The secret is shown exactly once — on the screen that created the key. We store only a hash of it. If you lose it, rotate the key; nobody at ShipEasy can recover it, and nobody should ask you for it.
One exception, stated plainly: if you ask ShipEasy support to issue a key for you — because whoever holds your owner account is unavailable — the operator who does it sees that one secret on their screen, and it is recorded against their name. Rotate it once you can, and the copy they saw stops working.
The checksum lets us reject a mistyped key without a database lookup.
Live and test keys#
A key's mode is fixed at creation and matches the environment it was created
in. A test key against live data — or the reverse — is refused with
api_key_mode_mismatch before any of your organization's data is read.
Test-mode bookings charge Stripe test cards and never move real money.
Test keys are issued on request. Email support@shipeasyco.com.
Scopes#
A key carries only the permissions you tick when you create it. Anything else
comes back 403 insufficient_scope. Grant the narrowest set that does the job:
a warehouse system that only prints BOLs needs shipments:read and nothing
else.
| Scope | What it allows |
|---|---|
account:read |
Read your organization's profile, quotable carriers, and API usage. |
quotes:read |
List and read rates you have already requested. |
quotes:write |
Rate new lanes. Each rated lane counts against your daily quote limit. |
bookings:read |
Read the status and receipt of a booking. |
bookings:write |
Spends money. Buy a quote — charged to a card enabled for API bookings, or invoiced — and list those cards to name one. |
shipments:read |
List shipments, read tracking, download the BOL. |
shipments:write |
Changes carrier instructions. Refresh tracking on demand; cancel a shipment, which can trigger a refund. |
addresses:read |
List saved origins and recent consignees. |
addresses:write |
Create, edit and delete saved origins and consignees. |
payments:read |
List your organization's invoices, payments and shared cards. Never returns card numbers. |
payments:write |
Money. Get a Stripe link to pay an invoice or add a card, and rename, share or remove a card. Never charges a card itself. |
catalog:read |
Read your catalog, or a Shopify store's package sizes. |
catalog:write |
Add, edit, remove and import catalog models, or a store's package sizes. |
support:read |
Read support cases, and the bell's notices of the member behind the key. |
support:write |
Open and answer support cases, send feedback, and ask for White Glove. |
documents:read |
Read and download the documents in your library. |
settings:read |
Read quoting defaults, notifications, branding, text alerts and referrals. |
settings:write |
Change quoting defaults, notifications, branding and text alerts. |
team:read |
List members, their roles and switches, and open invitations. |
team:write |
Who gets in. Invite, change, suspend or remove members, never the owner. |
developers:read |
List API keys, webhook endpoints and connected AI apps. Never a secret. |
developers:write |
Credentials. Create, rotate and revoke keys with no more than this key may do; add or remove webhook endpoints; disconnect other AI apps. |
analytics:read |
Read the analytics report and download it as a CSV. |
The API never accepts a card number, in any field, under any scope:
payments:write hands the person a link. A card is added, and allowed for API
bookings, by a person at /portal/payment-methods, and
an invoice is paid on Stripe's own page.
The newer scopes (catalog, support, documents, settings, team, developers,
analytics and payments:write) answer while ShipEasy's newer areas are on for
your account; until then their endpoints answer unknown_endpoint.
Only your organization's owner or an admin can create a key (or ShipEasy support,
when you ask, as above), and they may tick any of these scopes. Scopes cannot be
changed after a key is created; rotating keeps them as they are. A key holding
bookings:write, shipments:write, addresses:write, team:write,
developers:write or payments:write acts with an admin's authority, so store
it the way you would an admin's password.
Every organization has API access unless ShipEasy has switched it off. If it has, ask for it back with Request access on AI & API in the web app's menu (/portal/ai).
The person behind a key#
Some things in the web app belong to one member rather than to the whole organization: the bell's notices, calendar subscribe links, and who a support message is from. For those, an organization's key acts for the member behind it: the person who connected the AI app, or else the person who made the key, while they are still an active member of the organization. They never get more than the key's scopes allow, and never more than the member's own role and switches.
A key nobody stands behind (one ShipEasy support made for you, or one whose
maker has left) answers those operations with 403 insufficient_scope, and
opens support cases under the organization's name.
Managing keys#
/portal/api-keys opens with a Connection panel — the base URL to copy, whether this deployment mints live or test keys, and how much of today's quota your organization has already spent against each of the three meters. Reading the page never charges a meter. Its AI agents (MCP) box gives the address an AI app connects to and how; see AI agents.
Below it, your organization's owner or admin can create, rotate and revoke keys. The web app asks for your password again before it creates or rotates one.
Create a key — name it after the system that will use it, not the person who made it. The name is how you will tell four keys apart in eighteen months. You can attach a contact email; booking confirmations for freight this key books go there if your organization has no notification email set.
Rotate a key — mints a replacement and puts the old one into a 24-hour
grace window during which both work. Deploy the new key, confirm traffic has
moved (last used on the old key stops advancing), and the old key stops
working when the window closes. No broken window, no coordinated cutover.
last used updates at most every five minutes, so wait at least that long
before you decide the old key is idle.
Keys have no expiry date. A key works until it is rotated, revoked or disabled.
Revoke a key — stops it immediately. There is no undo and no grace period. Use it the moment a key might have leaked.
An AI app connected by signing in (claude.ai, Claude Desktop, ChatGPT; see
AI agents) holds a key
too, listed under Connected apps on /portal/ai, not with
your keys. It works only at /mcp,
renews itself every hour, and cannot be rotated: Disconnect it, and connect
it again from the app. It is also disconnected when the person who connected it
signs out everywhere or changes their password; ordinary keys are the
organization's and are left alone.
ShipEasy support can also disable a key — for abuse, or at your request out
of hours. A disabled key returns 403 api_key_disabled, and your organization
cannot clear it from the web app; rotating will not restore it either. Email
support@shipeasyco.com.
What each refusal means#
| Code | Status | What happened | What to do |
|---|---|---|---|
api_unavailable |
503 | The API is not available right now, or we could not count the request against your usage. Retry after Retry-After. |
Retry later. |
rate_limit_exceeded |
429 | Too many calls from this key in a minute. | Wait Retry-After seconds. |
missing_api_key |
401 | No Authorization header, or not a Bearer one. |
Send the header. |
invalid_api_key |
401 | Malformed, or no such key, or the wrong secret. | Check for a truncated copy-paste. |
api_key_mode_mismatch |
401 | A test key against live, or a live key against test. | Use the key for this environment. |
api_key_expired |
401 | Past an expiry date. Keys made in the web app have none; an AI app's hourly token lapses between renewals. | Create a new one; an AI app renews its token on its own. |
api_key_revoked |
401 | Someone at your organization or store revoked it, or disconnected the AI app. | Create a new one, or connect the AI app again. |
api_key_rotated |
401 | Rotated, and the grace window has closed. | Switch to the replacement. |
api_key_disabled |
403 | ShipEasy disabled it. | Email support@shipeasyco.com. |
api_disabled_for_organization |
403 | ShipEasy has switched your organization's API access off, or suspended it. | Email support@shipeasyco.com. |
organization_inactive |
403 | Your organization is not active. | Email support@shipeasyco.com. |
daily_quota_exceeded |
429 | The requests meter — your organization's, or this key's own — is spent for the day. |
Wait for 00:00 UTC. See rate limits. |
insufficient_scope |
403 | Valid key, wrong permissions. | Create a new key with the scope. |
401 means the credential is the problem. 403 means the credential is fine and the answer is still no — retrying with a fresh token will not help. 429 and 503 are about load and availability, not the key: wait, then retry.
Every refusal after a key's secret checks out, these included, is counted against that key for your owners and admins to see under AI & API → Usage & problems. A wrong or unknown key counts against nobody. See refusals you can see.
Storing a key#
Warning: This API is server-to-server only. A key in browser JavaScript is a key you have published.
- Keep it in your secret manager, not in source control, not in a
.envyou commit, and not in a frontend bundle. - One key per system, so you can revoke one without stopping the others.
- Rotate on a schedule, and immediately if someone who had access leaves.
- If you think a key has leaked, revoke it first and investigate second.
Checking what a key can do#
/api/v1/accountScope account:readcurl https://app.shipeasyco.com/api/v1/account \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "account",
"organization": { "id": "cm1z0a2b3…", "name": "Acme Freight", "status": "active" },
"carriers": [
{ "key": "ait", "name": "AIT Worldwide Logistics", "scac": "AITW" },
{ "key": "ceva", "name": "CEVA Logistics", "scac": "CEVA" }
],
"shipping": {
"pickup_min_business_days": 1,
"default_package_type": "pallet",
"white_glove_approved": false
},
"booking": {
"enabled": true,
"terms_accepted": true,
"billing_paused": false,
"billing_mode": "card",
"max_amount_usd": null,
"ready": false,
"blockers": [
{
"code": "card_not_enabled_for_api",
"message": "No card is enabled for API bookings yet. Someone with authority turns one on under Payment methods in the web app.",
"fix_url": "https://app.shipeasyco.com/portal/payment-methods"
}
],
"payment": { "mode": "card", "default_card": null, "enabled_cards": 0 }
},
"insurance": {
"available": true,
"rate_per_100_usd": "…",
"minimum_premium_usd": "…",
"min_declared_value_usd": "…",
"coverage_limit_usd": "…",
"deductibles": [
{ "up_to_usd": "…", "deductible_usd": "…", "deductible_percent": null }
],
"bind_cutoff_hour_et": 24,
"terms_version": "2026-11-06-a",
"terms": "I confirm my declared value is accurate, …",
"summary_url": "/insurance"
},
"usage": {
"requests": {
"used": 412,
"limit": 10000,
"remaining": 9588,
"resets_at": "2026-10-29T00:00:00.000Z"
},
"quotes": {
"used": 38,
"limit": 1000,
"remaining": 962,
"resets_at": "2026-10-29T00:00:00.000Z"
},
"bookings": {
"used": 4,
"limit": 100,
"remaining": 96,
"resets_at": "2026-10-29T00:00:00.000Z"
},
"degraded": false
},
"min_poll_interval_seconds": 60,
"connection": {
"kind": "ai_app",
"areas": ["book", "shipments"],
"missing_areas": ["catalog", "settings"],
"change_url": "https://app.shipeasyco.com/portal/ai"
}
}booking is the useful part before your first booking. ready is true when
nothing about the account would stop one; otherwise blockers lists each
reason, in the order a booking checks, with the error code the booking would
answer and a fix_url — the web app page where a person fixes it, or null
when only support can. A ChatGPT connection never books from the chat, so its
blockers hold one entry saying where booking happens instead
(ChatGPT). payment says how a booking is paid (card, invoice,
or simulated in a sandbox) and, on card, which card is used when you name
none: default_card is set only when exactly one card is enabled. enabled and
terms_accepted must be true and billing_paused false (enabled is false
while ShipEasy has paused card bookings, for an organization that pays by card); billing_mode says
whether you send a card (card) or are invoiced (invoice); max_amount_usd
is this key's per-booking ceiling — a two-place string such as "5000.00" — or
null when it has none.
insurance is what cargo coverage costs and whether it can be bought now. See
booking for how the premium is worked out.
usage is today's spend on each daily meter. degraded is true when we could
not read the counters in time: requests is then still this call's own count,
but quotes and bookings read as nothing used, a floor rather than a fact.
See rate limits.
carriers is the intersection of what ShipEasy contracted for you, what you
have enabled in settings, and what is currently running — so it can never advertise a carrier a quote would refuse.