API Keys and Connected Apps

API access comes with Plus. Everything the web app does -- rating, labels, tracking, address validation, voiding -- you can do through our GraphQL API too, because the web app is built on the very same API you get.

You'll find and manage your keys on the Connected Apps page.

Apps and Keys

Access starts with an app, not a key. An app has a name, a set of permissions, and its own keys, and those keys inherit whatever permissions you give the app.

Each app gets two keys: production and sandbox. Sandbox keys are free and come with every app, and the sandbox endpoint they connect to is coming shortly. Until it's live, you can build against production with a tightly scoped key and run rates rather than buy labels -- rating is free, unlimited, and creates nothing you'll need to void afterwards.

It's worth creating one app per integration rather than one app for everything. That way, if you ever need to revoke access, you can switch off a single integration instead of everything you've built.

Creating an App

To create an app, give it a name and choose its permissions. Your keys appear immediately afterwards.

Copy them into your password manager or secret store while they're on screen. Keys stay hidden in the interface until you choose to reveal them, and you can always view one again from the key detail panel -- but storing them properly at creation time saves you the hunt later.

Scoping Permissions

You pick an app's permissions when you create it, and you can change them later. Give each app the narrowest set that still lets it do its job.

A few common setups:

• A rate calculator on your storefront needs rating and address validation, but nothing that creates shipments.
• A fulfillment integration needs to create shipments and read tracking, but nothing that manages carrier accounts or users.
• A reporting job only needs read access to shipments -- nothing more.

This matters because permissions decide how much damage a leaked key can do. A read-only reporting key that gets out is something you can clean up quickly; a key that can buy postage is a much more expensive problem.

Authenticating

Send your key as a bearer token:

Authorization: Bearer YOUR_API_KEY

Endpoints:

• Production -- https://api.lite.shipgeni.us/graphql
• Sandbox -- https://sandbox.lite.shipgeni.us/graphql, coming shortly

Confirm your credentials with the ping query first. It returns your app name, the IP address the request came from, the permissions your key actually carries, and the current server time. It's the quickest way to tell whether your key is wrong or your query is wrong -- and if an operation is being refused, the permissions it lists will usually tell you why.

Managing Keys

Pause and Resume

Pausing a key stops it working without deleting it. It's a good first move if you think a key may have leaked but aren't sure yet -- it takes effect instantly, and you can resume the key if it turns out to be fine.

Rotate

Rotation issues a new key and schedules the old one to expire. You choose when the old key stops working:

• Immediately
• In one hour
• In one day
• In one week
• In four weeks

That delay is what lets you rotate without any downtime. Rotate with a week's overlap, deploy the new key, check that your traffic has moved over, and let the old one expire on schedule.

Choose immediately only when you know a key has been compromised. The rest of the time, give yourself an overlap window.

Delete

Deleting a key is permanent and takes effect right away, so anything still using it stops working immediately. If you only need a key out of service for a while, pause it instead.

Delete an App

Deleting an app removes the app and both of its keys. You'll be asked to type the app's name to confirm, since it can't be undone.

Keeping Keys Safe

• Keep keys out of source control. Automated scanners comb public repositories for them around the clock, so a key that lands in a commit tends to get found.
• Keep keys out of client-side code. Anything that ships to a browser or a mobile app can be read by anyone who cares to look.
• Store keys in environment variables or a secret manager.
• Use a separate app for development, with a key scoped to only what that environment needs.
• Rotate on a schedule, not just after something goes wrong. A rotation you've done before is one you can do calmly on the day it counts.
• Rotate right away when someone with key access leaves.

Keys Are Not Users

An API key authenticates as an app rather than as a person. It carries the app's permissions, it has no second factor, and the MFA requirements that apply to a signed-in user don't apply to it.

That's intentional -- an automated integration has no way to answer an MFA challenge -- and it's why tight permissions matter even more for keys than they do for people. Someone signing in with broad permissions still has a second factor in the way; a key doesn't, so its permissions are the whole of its protection.

Where to Go Next

You'll find the full API reference, including the schema explorer and a quickstart, in the developer section of the app. The rating, shipping, tracking, and address validation operations each have their own documentation, with input and response types linked.

FAQs

Do I need a paid plan for API access?

Yes -- API access comes with Plus. Sandbox access is included with any app you create.

What's the difference between sandbox and production keys?

Sandbox is a testing environment: it doesn't create real labels or charge you for postage, while production does both. Sandbox keys come with every app, and the sandbox endpoint is coming shortly.

I lost my API key.

You can view it again from the key detail panel, or rotate the key to issue a new one. Rotating is the safer choice if you're not certain where the old key ended up, and it only takes a moment.

How do I rotate a key without downtime?

Rotate with a delayed expiry -- a week is comfortable -- then deploy the new key, confirm your traffic has moved over, and let the old key expire on schedule.

Can one app have multiple keys?

Each app has one production key and one sandbox key. If you need separate access paths, create separate apps -- that's also what lets you revoke one integration without disturbing the others.

Why is my key getting permission errors?

Run the ping query. It returns the permissions your key actually carries, which is usually where the mismatch turns up. If the operation you need really is missing, edit the app's permissions to add it.

Can I restrict a key to specific IP addresses?

Not at the moment -- access is scoped by permissions rather than by network address. Keeping the permission set narrow, rotating regularly, and storing keys in a secret manager rather than in code covers most of the same ground. If IP restrictions matter for your setup, get in touch and let us know.