warden

Integrate

Make a key

An admin makes an integration key in Commercial. The key is shown once.

An integration key is what your server sends with every request. An admin of the organization makes it, signed in as themselves. This is the one step a key cannot do for itself. The API is part of the Creator and Studio plans, and on a plan without it Warden refuses to make a key.

  1. Open Commercial, then Your integration

    The page says how records arrive and lists the keys this organization has made. A member who is not an admin cannot read the list or make a key.

  2. Name it and choose a provider name

    What you call it is a label for you, up to 80 characters. The provider name is one word you choose for your system, up to 80 characters, and every record the key writes is filed under it.

  3. Choose what else it may do

    Tick Can also send shop registration deadlines only for a key that will send registration deadlines. Every key can write and read entitlements.

  4. Make the key and copy it

    The key appears once, with a copy button. Put it in a server-side secret before you leave the page.

After that the list shows the key's name, its provider name, the first characters of the key, whether it may send shop deadlines, when it was made, and when it was last used.

What a key can reach

One organization and one provider name. It can write and read entitlements under that provider name in that organization, and issue enrollment invitations for them. A key granted shop_status can also send registration deadlines. It opens no other route. No request you send names an organization, because the key already does, and a body that names one is refused.

Rotate a key

Make a second key for the same provider, deploy it, then revoke the first. On a plan with room for only one key, revoke the first before making the second: a plan with no room for another key answers 403 with plan_not_allowed. Revoke asks once, then the key stops working at once and answers 401 from then on. A revoked key stays in the list with the day it was revoked, as the record that it existed.

From your own tooling

The page calls three routes, and an admin can call them directly with their own session token. They are the app's own routes, not the integration API: they are signed in with a person's session rather than a key, and they answer in camelCase. The snake_case rule in the API overview is about the integration routes.

GET /api/v1/integration/keys
Authorization: Bearer <the admin's own session token>
X-Warden-Org: <organization id>

Newest first, revoked keys included. A member who is not an admin gets 403 here too.

POST /api/v1/integration/keys
Authorization: Bearer <the admin's own session token>
X-Warden-Org: <organization id>
Content-Type: application/json

{ "name": "production reconcile", "provider": "yourshop", "scopes": ["entitlements", "shop_status"] }

scopes is optional. entitlements is always granted, and shop_status only when you name it. Any other field is refused. A member who is not an admin gets 403.

DELETE /api/v1/integration/keys
Authorization: Bearer <the admin's own session token>
X-Warden-Org: <organization id>
Content-Type: application/json

{ "id": "6f0c2a1e-5b7d-4c3a-9e21-0d4f8a6b7c90" }

The answer is 204 with no body.