Skip to content
Try the admin demo 0

Admin module

A REST API with keys you can revoke

Admin → API Manager issues keys, decides what each one may do and writes down every request it makes. The API itself is six routes. This page is the whole of it.

Ask it something

Every call carries a key, in a header. There is no session, no cookie and no login form.

With a key

curl -H "Authorization: Bearer mpk_1a2b3c4d5e6f.…" \
     https://your-site/api/v1/posts

{
  "data": [ { "id": 12, "slug": "pricing", "lang": "en", … } ],
  "meta": { "count": 34 }
}

Without one

curl https://your-site/api/v1/ping

{
  "error": {
    "code": "unauthorized",
    "message": "A valid API key is needed:
      Authorization: Bearer mpk_… or X-API-Key."
  }
}

A key may do less than you can, never more

When you create a key you tick the scopes it needs. The panel then cuts that list down to what you are allowed to do: a key made by an editor cannot read orders, however many boxes were ticked.

A route with no scope for it answers 403 and says which scope it wanted. Nothing is guessed and nothing is implied.

The five scopes

  • posts.read — read published pages and articles
  • orders.read — read orders
  • orders.write — create orders, that is payment links
  • customers.read — read customers
  • customers.write — create or complete customers

Six routes, and that is the list

GET   /api/v1/ping                 no scope, tells you the key works
GET   /api/v1/posts                posts.read
GET   /api/v1/orders               orders.read
POST  /api/v1/orders               orders.write   -> returns a payment link
GET   /api/v1/customers            customers.read
POST  /api/v1/customers            customers.write

Anything else answers 404 with a message telling you to look in the panel. The routes do not change when a module is switched on or off.

Shown once, stored as a hash

A key looks like mpk_1a2b3c4d5e6f.<40 hex>. The part before the dot identifies it; the part after is the secret, and the database keeps only a SHA-256 of it.

So the panel can show you a key exactly once, when it is made. After that nobody can read it back — not you, not an administrator, not somebody with a copy of the database. If it is lost, you make another and switch the old one off.

What a key carries

  • A name, so you know what it is for
  • Its scopes
  • An hourly limit of its own
  • An expiry date, if you set one
  • An on/off switch that takes effect at once

Limits, and a log you can read

Each key has its own requests-per-hour figure, set when you make it. Wrong keys are counted separately, per address: fifty failures in an hour and that address is refused, so the key format cannot be guessed at leisure.

Every request is written down — the key, the method, the route and the status — and kept for 90 days, then deleted. When an integration starts misbehaving, the answer is in a table rather than in a guess.

The API Manager in action

The screenshot below shows the keys, the routes and the form for a new one. Clicking it opens a full size preview.

API Manager: the keys with their scopes and rate, the route table, and the form for a new key
Each key with what it may do and how many requests an hour it gets. The key itself is shown once, when it is made, and never again.