Skip to content

Authentication & keys

Contents 26 pages

Every request carries an API key as a bearer token:

Authorization: Bearer se_live_7qk3m2a9_TFhCS0JnLTBqVFlvNGZfMV81dGhrRWFxV0k3ekYzVXM_3k7m2q

There 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 prefix

Two 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 .env you 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#

GET/api/v1/accountScope account:read
Request
curl https://app.shipeasyco.com/api/v1/account \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"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.