Guides

Authentication and keys

Every request to the Uncart API carries one key, in the Authorization header. The key says which shop the request is for and which data it may touch.

An owner of the shop makes keys on the dashboard's Connection page (Shop setup, then Connection). If your Connection page says making keys comes later, Uncart's team makes them with you: write to hi@uncart.ai. Rotating and revoking work on the page either way.

Secret keys

PrefixUse it
uc_live_On your server, for live data
uc_test_On your server and in CI, for test mode

A secret key belongs on a server. Never put one in a browser, an app or a repository.

A publishable key (uc_pk_) is made to be public, for your storefront's pages. It carries only the storefront scope, and a secret key never does.

A key is its prefix followed by 65 letters and digits. They are a 16-character key id, a 43-character secret, and a 6-character checksum. The checksum lets Uncart refuse a mistyped or truncated key before any lookup. It also lets a secret scanner tell a real Uncart key from random text. Uncart shows a key once, when it is made, and keeps only a keyed hash of it. If you lose a key, get a new one.

Sending the key

Send the key as a bearer token, Authorization: Bearer uc_test_…, and nowhere else.

Never put a key in a URL. URLs are written to logs and browser histories, so Uncart refuses any request with a key in its path or query string, even percent-encoded and even when the header is right. Treat a key you have sent that way as leaked, and have it replaced.

Every refusal gets the same answer, status 401 with the body below. A missing key, a wrong one, a revoked or expired key, a test key on live data and a key without the scope all look alike from outside. Only Uncart's own logs keep the reason.

JSONAnswer 401
{
  "error": "unauthorized",
  "message": "A valid API key is needed, in the Authorization header.",
  "request_id": "req_00000000000000000000000000000000"
}

When Uncart cannot check keys at that moment, because too many unknown keys arrived at once, it answers 503 with Retry-After: 1. Send the same request again after a second. Your key is fine.

Scopes

A secret key carries one or more scopes. Each route lists the scopes it accepts, and a key needs one of them. Give each system a key with only the scopes its routes need. These are the routes each scope opens.

Rotating a key

Rotating makes a new key with the same mode, kind and scopes. The old key keeps working for the overlap you choose: none, one day (the default) or seven days. Deploy the new key and let the overlap run out. A key is rotated once. Its new key can be rotated in its turn once the old one has stopped working.

You choose the overlap when you rotate on the Connection page. The page shows the date each key was last used. When the old key's date stops changing, nothing is using it.

A rotation never lengthens a key's life. If the old key had an end date, the new one stops working at the same moment.

When a key leaks

A leaked key is rotated with an overlap of zero, or revoked. Either one ends the old key at once, on every Uncart server.

Rotate it with an overlap of zero on the Connection page, or revoke it there.

Who can manage keys

Only an owner of the shop can make (where the Connection page offers it), rotate or revoke a key, and only after entering their second factor in the last ten minutes. Key changes are blocked for 24 hours after an account was recovered. Owners can see the list of keys at any time. It never shows a key's secret. Every change to a key is written to the history of the account that made it.