API keys and the developer API

The developer API lets you read and change a shop's screens, theme and custom blocks from code.

Status: built. Needs setup: the shop owner or an admin creates the key.

Create a key#

1. Open the developer keys page in the admin. This needs the integration manage permission.
2. Choose the scopes the key needs. Choose the smallest set.
3. Set an expiry. The default is 180 days. The maximum is 365 days.
4. Create the key. The full key is shown once. Copy it to a password manager.

A shop can have up to 20 active keys. Revoke a key to stop it at once.

The key looks like abk_ followed by 8 hex characters, then 43 characters. The app stores only a hash of the key. It cannot show you the key again.

Scopes#

A key with only read scopes cannot write.

Calling the API#

Send the key in a header:

Authorization: Bearer abk_...

Routes live under /dev/v1:

• whoami: check the key and its scopes.
• screens: list screens, read one, and save a draft with PUT :key/draft.
• theme: read the theme, and save a draft with PUT theme/:key/draft.
• validate: check a screen, theme or custom block without saving.
• blocks: list, read and save custom blocks.
• preview: make a preview link.
• publish: publish all drafts.

Drafts and conflicts#

• A draft save must send base_version_id, the version you last read. If someone changed the screen since, the save is refused. Pull again and retry.
• A draft that uses a custom block which fails its definition is refused with status 422.
• Every save is recorded in the audit log, with the key prefix as the actor.

Publishing#

publish checks the approval rules first. If an approval rule applies, the call returns status 202 with an approval ID. Nothing goes live until someone approves it. Keys never skip approvals.

Error handling#

All failures from a bad or revoked key give the same 401 response. This is on purpose. It does not tell an attacker which part was wrong.

Keys stop working when the shop uninstalls the app.