Reference›Platform API

Platform API#

What does each platform route take and answer, and how is a call signed?

A platform is a business that serves its own users through Mehen (Platforms and managed workspaces). It calls the vault at https://app.mehen.dev, under /v1/platform, with JSON in and out. Build on Mehen walks through the calls in order; @mehen/client's platform client makes every one of them for you. The tables on this page are generated from the route table in Mehen's protocol, so they say what the vault named in the footer accepts.

Signing a call#

Every call carries a Mehen-Platform-Proof header: a compact JWS, signed with the platform's own P-256 key, over that one request. There is no bearer token, so nothing on the platform's disk or in a log can be replayed.

header  { "alg": "ES256", "typ": "mehen-platform+jwt", "kid": "pky_..." }
payload { "plt": "plt_...", "sub": "<subject>", "htm": "POST", "htu": "https://app.mehen.dev/v1/platform/...", "bh": "<base64url SHA-256 of the body>", "iat": 1793270400, "jti": "<random>" }

The proof's typ and header differ from a machine's Mehen-Proof, so neither can stand in for the other, and a platform call that also carries Mehen-Proof is refused with bad_request. The vault checks the proof in this order: the key by its id, with no cache; the signature, method, URL, body hash, time and subject; the platform's status; then the nonce, spent once per key, and the platform's limits. Keys, proofs and signing has the details.

Subjects#

A subject is the platform's own name for one of its users: 8 to 128 of A-Z a-z 0-9 _ -. Mehen never interprets it, and it is unique within its platform only: the vault finds a workspace from the verified platform and the subject together, so another platform naming the same string reaches its own workspace or none. Choose a subject that says nothing about the person, and never reuse one.

Answers and refusals#

A success is the JSON the route's table gives. Answers may gain members in later releases; read what you know and ignore the rest. No answer carries a secret value, a client secret, a token, a link to a Mehen page or a command to run.

A refusal is the error object of Errors and exit codes, with the header Mehen-Error: 1 and the HTTP status that page gives its code. Two codes are only ever a platform's: platform_suspended and quota_exceeded.

In a managed workspace, a refusal a machine gets on the ordinary machine routes carries no link: approval_required names the approval and its binding code for the platform to decide, and needs_reauth says the platform reconnects the account. HTTP surfaces lists how each machine route answers there.

Routes#

Every route is under /v1/platform and carries Mehen-Platform-Proof. In the tables below, a nested member such as a.b is required within its parent, a[].b is a member of each item of the array a, and a.<name>.b a member of each value of the map a. The platform's own routes:

One subject's routes, each under /v1/platform/subjects/:subject:

Common refusals#

Any route may answer these, beyond its own. Every refusal is an error object with the header Mehen-Error: 1.

Limits#

Mehen's operator sets each platform's limits when it registers the platform, and may change them later. Every managed workspace reads them live; past one, a route answers quota_exceeded or rate_limited. The defaults:

The platform#

platform.view#

GET /v1/platform

Reads the platform as Mehen holds it: its status, limits, defaults and their revision, how many subjects it has, and its keys.

Answer (200).

Its own refusals: none beyond the common ones.

subjects.list#

GET /v1/platform/subjects

Lists the platform's own subjects, a page at a time, with each one's status. Another platform's subjects are never listed.

Query. Every value is a string on the wire.

Answer (200).

Its own refusals: none beyond the common ones.

defaults.put#

PUT /v1/platform/defaults

Replaces the platform's defaults: which templates and providers its users may add, default OAuth scopes and tags, rules added to a template's or provider's policy, and whether keys with no template may be read without a hold. Rules may only hold or refuse, never allow. Every workspace uses the new defaults within 30 seconds, and approvals made under the old ones go stale.

Body.

Answer (200).

Its own refusals: none beyond the common ones.

The table gives a rule's action as the policy shape allows it; a platform's rule may only be approve or deny, and an allow rule is refused with bad_request. So are a template, provider or scope the catalogue lacks, and a tag given twice.

subjects.removeAll#

DELETE /v1/platform/subjects

Deletes every subject the platform has, each as deleting one does, 50 at a time. confirm must be the platform's own slug. The platform stays registered.

Body.

Answer (200).

Its own refusals: none beyond the common ones.

A subject#

Every route here names one subject in its path, and its proof's sub claim must be that same subject. A subject the platform does not have is not_found, exactly as one that never existed.

subjects.ensure#

PUT /v1/platform/subjects/:subject

Makes sure the subject has its managed workspace: 201 when it is made, 200 when it already existed. Refused while the subject is still being deleted, and while the platform is retiring.

Path.

Body. {}

Answer (200 or 201).

Its own refusals, beyond the common ones: quota_exceeded, conflict.

subjects.get#

GET /v1/platform/subjects/:subject

Reads one subject: its status and how many devices, items and projects its workspace holds. A deleted subject is answered until its purge, so its audit can still be read.

Path.

Answer (200).

Its own refusals: none beyond the common ones.

subjects.remove#

DELETE /v1/platform/subjects/:subject

Deletes a subject: every device is revoked, every secret and item deleted, and the audit kept until the purge date in the answer, when the whole workspace is erased. Repeating it answers the same.

Path.

Body. {}

Answer (200).

Its own refusals: none beyond the common ones.

devices.create#

POST /v1/platform/subjects/:subject/devices

Provisions a device in the subject's workspace for one of the platform's agents, with no enrolment page. It may only relay and serve placeholders, and acts only through workloads. The same key again answers the existing device with 200.

Path.

Body.

Answer (200 or 201).

Its own refusals, beyond the common ones: quota_exceeded, conflict, frozen.

devices.list#

GET /v1/platform/subjects/:subject/devices

Lists the subject's devices, with when each was last seen and how many live workloads it has.

Path.

Answer (200).

Its own refusals: none beyond the common ones.

devices.revoke#

DELETE /v1/platform/subjects/:subject/devices/:device

Revokes a device. Its workloads, open asks and runs end with it. Repeating it answers the same.

Path.

Answer (200).

Its own refusals, beyond the common ones: frozen.

items.list#

GET /v1/platform/subjects/:subject/items

Lists the subject's items by Mehen's metadata (name, kind, provider, account, tags, hosts, status and policy). Never a value.

Path.

Query. Every value is a string on the wire.

Answer (200).

Its own refusals: none beyond the common ones.

items.remove#

DELETE /v1/platform/subjects/:subject/items/:slug

Deletes an item and its secrets. Approvals and grants on it end. An OAuth connection's token is handed back to the provider first where the provider allows it.

Path.

Answer (200).

Its own refusals, beyond the common ones: frozen.

intakes.create#

POST /v1/platform/subjects/:subject/intakes

Opens a request for a credential and answers the vault's seal key and the fields to fill in: a key from a catalogue template or for one host, or the person's own OAuth app, for a catalogue provider (with its set-up steps) or with its own provider definition. The person types the values into the platform's own page, which seals each secret in their browser before it reaches the platform. An existing name of the same kind is a rotation and keeps where the key may go. It lives 10 minutes and carries no link.

Path.

Body.

Answer (201).

Its own refusals, beyond the common ones: conflict, quota_exceeded, frozen.

service is one of three shapes. { template } names a catalogue template: a key's, or a provider's app template such as google-oauth-client, whose answer carries the template's set-up steps in setup, each body possibly holding {callback} for the platform's page to replace with its own callback URL. { host } is a key for one API host with no template; every request with it is held unless the platform's customReads lets reads through. { customProvider } is the user's own OAuth app with its own provider definition: authorizeUrl and tokenUrl are https on a public host name, with no user name, password or fragment, and never an IP address or a private name; authorizeParams holds at most 8 names, none that Mehen sets itself; each scope and host appears once. The shape allows clientAuth: "none", a public app with no secret, but the vault does not support one yet and refuses its intake with bad_request. The definition is fixed with the app, and the app's client secret is bound to the token URL's host and path, by POST, so it is sent nowhere else. A template outside the platform's templates default is bad_request. A slug the user already has is a rotation of that credential: of another kind or service it is conflict, and so is a different definition under an existing app's name.

intakes.submit#

POST /v1/platform/subjects/:subject/intakes/:intake/submit

Submits the sealed values for an open request. Each box opens only for this request and field, and only once. The name, where the key may go, its tags and its home are the request's, never the body's.

Path.

Body.

Answer (200).

Its own refusals, beyond the common ones: conflict, quota_exceeded, frozen.

Seal each field the intake marked secret under intake/<intake>/<field>, and send the others, such as an OAuth app's client_id, in publicFields.

intakes.cancel#

POST /v1/platform/subjects/:subject/intakes/:intake/cancel

Cancels an open request for a credential.

Path.

Body. {}

Answer (200). {}

Its own refusals: none beyond the common ones.

connects.start#

POST /v1/platform/subjects/:subject/connects

Starts connecting an account with the person's own OAuth app, held in their workspace, and answers the provider's authorisation URL, carrying Mehen's state, the platform's callback and a PKCE challenge where the provider supports one, for the platform to send the person to. Without scopes it asks for the platform's default scopes for a catalogue provider, else the catalogue's, or every scope of the app's own provider definition. It lives 15 minutes.

Path.

Body.

Answer (201).

Its own refusals, beyond the common ones: conflict, quota_exceeded, frozen.

Name a catalogue provider, and optionally the client, the user's app for it (by default the app named after the provider's app template, such as google-oauth-client); or name only the client, an app with its own provider definition. redirectUri is the platform's own callback, exactly as the user registered it in their app. A provider outside the platform's providers default is bad_request. An existing connection's slug is a reconnect: for a catalogue provider, pinned to the same account at the provider; for an app with its own definition, through the same app. A device's own POST /v1/connect is refused with forbidden in a managed workspace: connections start here.

connects.finish#

POST /v1/platform/subjects/:subject/connects/finish

Finishes a connection with what the platform's callback received. Mehen exchanges the code with the app's client secret, which only Mehen holds, and its own PKCE verifier where it sent a challenge, so the code is useless to anyone else. A state that is not this subject's is not found; a state already used or expired is a conflict.

Path.

Body.

Answer (200).

Its own refusals, beyond the common ones: conflict, quota_exceeded, upstream_failed, frozen.

Send the state and either the code or the provider's error from the callback, never both. Name the subject who is signed in to the platform at the callback, not the one the platform expects. A completed connection made with a catalogue provider names the account the provider verified; one made with an app's own definition names none.

connects.get#

GET /v1/platform/subjects/:subject/connects/:connect

Reads a connection's progress and outcome.

Path.

Answer (200).

Its own refusals: none beyond the common ones.

connects.cancel#

POST /v1/platform/subjects/:subject/connects/:connect/cancel

Cancels a connection that has not finished.

Path.

Body. {}

Answer (200). {}

Its own refusals: none beyond the common ones.

approvals.list#

GET /v1/platform/subjects/:subject/approvals

Lists the subject's held requests, filtered by status.

Path.

Query. Every value is a string on the wire.

Answer (200).

Its own refusals: none beyond the common ones.

approvals.get#

GET /v1/platform/subjects/:subject/approvals/:approval

Reads one held request: the exact request it would send, its digest, the device and workload that asked, what Mehen could not read, and who decided it.

Path.

Answer (200).

Its own refusals: none beyond the common ones.

approvals.decide#

POST /v1/platform/subjects/:subject/approvals/:approval/decide

Approves or denies a held request, naming its digest. An approval is good for one use of that exact request by the workload that asked, for at most the platform's decision limit (15 minutes at most). A digest that is not the request's, or a request no longer pending, is a conflict: the request changed, ask again.

Path.

Body.

Answer (200).

Its own refusals, beyond the common ones: conflict, frozen.

projects.create#

POST /v1/platform/subjects/:subject/projects

Creates a project, a named set of settings and keys for computers, with its environments. Every environment is unprotected. The same name again, with the same environments and default environment, answers the existing project with 200; the same name with other environments or another default environment is a conflict.

Path.

Body.

Answer (200 or 201).

Its own refusals, beyond the common ones: conflict, quota_exceeded, frozen.

projects.get#

GET /v1/platform/subjects/:subject/projects/:project

Reads a project and its variables, plain values included.

Path.

Answer (200).

Its own refusals: none beyond the common ones.

projects.setVar#

PUT /v1/platform/subjects/:subject/projects/:project/vars/:name

Sets one variable in one environment to a plain value or an item's field, or unsets it when neither is sent. before is the value last read; a stale one is a conflict. A plain value that looks like a secret is refused.

Path.

Body.

Answer (200).

Its own refusals, beyond the common ones: conflict, frozen.

projects.remove#

DELETE /v1/platform/subjects/:subject/projects/:project

Deletes a project. Its runs and their placeholders end.

Path.

Body. {}

Answer (200).

Its own refusals, beyond the common ones: frozen.

audit.read#

GET /v1/platform/subjects/:subject/audit

Reads the subject's audit chain a page at a time, every row, with its head and whether it verified. Every row names the platform.

Path.

Query. Every value is a string on the wire.

Answer (200).

Its own refusals: none beyond the common ones.

workspace.freeze#

POST /v1/platform/subjects/:subject/freeze

Freezes the subject's workspace: nothing is used or changed until it is unfrozen.

Path.

Body. {}

Answer (200).

Its own refusals: none beyond the common ones.

workspace.unfreeze#

POST /v1/platform/subjects/:subject/unfreeze

Unfreezes the subject's workspace.

Path.

Body. {}

Answer (200).

Its own refusals: none beyond the common ones.