API Reference

API Reference

All endpoints are relative to the Vault base URL and are prefixed with /api/v1.

There are two authentication mechanisms across the API:

• Client authorization — the request body carries the client’s clientId and clientSecret. Used for endpoints where the client acts on its own behalf.
• User authorization — the Authorization: Bearer <access_token> header carries a user’s token. Used for endpoints where the acting party is the user themselves.

Fetch the keyset

Retrieves the public keys of the availability the client is linked to. Fetch once at startup, cache, and use the keys to verify access tokens locally.

Body parameters:

Response:

[{ "kid": "<key_id>", "key": "<public_key>" }]

Each entry contains the key id (kid, matched against the access token header to select the verification key) and the public key itself.

Retrieve the role map

Returns the roles attached to the client as a { [label]: code } map. Use it to resolve the role codes carried in the access token’s roles array.

Body parameters:

Response:

{
  "readonly": "readonly_code",
  "admin": "admin_code"
}

The map contains only the roles attached to the requesting client — no filtering is required on your side.

Get the user profile

Applications may want to build their own user profile screens. Vault’s user data can serve as the reference for them.

Authentication:

Response:

{
  "id": "84cf3b03-9b28-4e8c-87a7-1685f1b7ad29",
  "oid": "6abebf76ad2a95dcef049679",
  "firstName": "John Doe",
  "lastName": "Richer",
  "email": "[email protected]",
  "username": "reacher",
  "verified": true,
  "mrn": "mrn:mkit:user:::O6ab4caMwJvG/ZcOVbey2wlqb",
  "slug": "ZcOVbey2wlqb",
  "isLocked": false,
  "roles": [],
  "realm": "3c489d65-450f-4555-a8a4-2b31a4582584"
}

Field notes:

Delete the current user

Hard-removes the user identified by the token. Intended to be called by client applications on behalf of a user requesting account deletion.

Authentication:

Response: the removed user entity.

Because the request carries the user’s own token, Vault identifies the target from the token itself — no user id is passed in the request, and a client can never purge anyone other than the requesting user.

Sync deleted users

Returns the realm’s purge entity collection — tombstones for users deleted within the retention window. Poll this endpoint to mirror user deletions in your own systems.

Body parameters:

Response:

The realm’s purge entity collection. Each entry contains the former user’s entity id, entityOid (if one existed), and the realm the user belonged to.