API reference

#Conventions

If you use the Swift SDK you never call these endpoints directly. This page is for developers implementing the protocol themselves or debugging an integration.

#Authentication

#Signatures

Apart from the token exchange, every third-party data call must carry both the access token and a signature from the grant's approval private key. A public client's revoke request is signed as well.

Canonical string (UTF-8, fields joined with \n, no trailing newline):

{METHOD}\n{PATH}\n{TIMESTAMP}\n{NONCE}\n{SHA256_HEX(BODY)}

• METHOD: the HTTP method in uppercase.
• PATH: the path without the query string, e.g. /api/oauth/requests/3f6b…/patch.
• BODY: the exact request body bytes you send. Do not modify the body after signing (including re-serializing it). With no body, use the empty string; its SHA-256 is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
• The timestamp must be within ±300 seconds of server time.
• A nonce can be used once per grant within a 10-minute window. A submitted nonce counts as used even if the signature check then fails.

GET /api/oauth/account HTTP/1.1
Host: password.tminos.com
Authorization: Bearer 3q2-7wEXAMPLEACCESSTOKEN
x-pm-timestamp: 1761177600
x-pm-nonce: n-0123456789abcdef
x-pm-signature: KngAgL1nChfn4NugEnlNlesKA8EtmrhpsL1GU9pU_Z0AcwkQRzP9iasdaFfe3nEVcvCGUT92eWHzzZCEX849DQ

You can reproduce this signature with the public test key in the test vectors.

Signature failures: signature_required (missing headers), signature_invalid (malformed values or bad signature), timestamp_out_of_window, nonce_replayed.

#Register a client

#POST /api/oauth/clients

Registers an integrating app. Authentication: account session. The Developer access page in MimiKey for Mac calls this endpoint.

POST /api/oauth/clients HTTP/1.1
Authorization: Bearer <session token>
Content-Type: application/json

{
  "name": "My AI Assistant",
  "description": "Signs in to websites to reconcile statements",
  "client_type": "public",
  "platforms": ["ios", "macos"],
  "redirect_uris": ["com.example.ai://mimikey/callback"],
  "brand": { "color": "#1d4ed8", "logo_url": "https://cdn.example.com/logo.png", "homepage": "https://example.com" }
}

{
  "client_id": "pmc_Xk3vQ9pL2mN8rT4w",
  "client_type": "public",
  "name": "My AI Assistant",
  "platforms": ["ios", "macos"],
  "brand": { "color": "#1D4ED8", "logo_url": "https://cdn.example.com/logo.png", "homepage": "https://example.com" }
}

For a confidential client the response also includes client_secret, returned this one time only; the server keeps only its hash.

Errors: invalid_input, invalid_client_type, invalid_redirect_uris, invalid_public_key, invalid_platforms, invalid_brand, mode_retired.

#GET /api/oauth/clients

Lists the clients registered by the current account. Authentication: account session.

{
  "clients": [
    {
      "client_id": "pmc_Xk3vQ9pL2mN8rT4w",
      "name": "My AI Assistant",
      "description": "Signs in to websites to reconcile statements",
      "client_type": "public",
      "redirect_uris": ["com.example.ai://mimikey/callback"],
      "platforms": ["ios", "macos"],
      "brand": { "color": "#1D4ED8" },
      "has_seal_key": false,
      "has_service_key": false,
      "disabled": false,
      "platform_disabled": false,
      "active_grants": 3,
      "created_at": "2026-10-23T08:00:00Z"
    }
  ]
}

disabled means the developer disabled the client; platform_disabled means the platform operator did.

#DELETE /api/oauth/clients/{id}

Disables a client. Authentication: account session. All of its grants are revoked, its tokens stop working and its unfinished requests expire; this cannot be undone. Returns { "ok": true }, or 404 client_not_found if the client does not exist or is already disabled.

#Consent (MimiKey app side)

The MimiKey app calls these endpoints with the user's account session. Integrators do not implement them; they are listed to explain the protocol.

#Deep links

The SDK starts MimiKey by opening one of these deep links:

For callback parameters, see the callback summary.

#GET /api/oauth/authorize/info

Data for the consent card. Query parameter: client_id.

{
  "client": {
    "id": "pmc_Xk3vQ9pL2mN8rT4w",
    "name": "My AI Assistant",
    "description": "Signs in to websites to reconcile statements",
    "client_type": "public",
    "brand": { "color": "#1D4ED8", "logo_url": "https://cdn.example.com/logo.png", "homepage": "https://example.com" },
    "platforms": ["ios", "macos"]
  },
  "vaults": [
    { "vault_id": "8d4c…", "name": null, "kind": "personal", "default": true },
    { "vault_id": "b2a1…", "name": "Family", "kind": "shared", "default": false }
  ]
}

Only vaults the user owns are returned. For v2 compatibility, client also contains client_id, seal_public_key and service_public_key. Errors: 404 client_not_found, 403 client_disabled.

#POST /api/oauth/authorize

Records the user's consent and issues an authorization code.

Response: { "code": "…", "state": "…" }. The code is valid for 10 minutes and can be used once.

#Tokens

#POST /api/oauth/token

No session required. Public clients must not send client_secret (doing so returns 400 invalid_client).

Exchange an authorization code:

POST /api/oauth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "q8V0…",
  "client_id": "pmc_Xk3vQ9pL2mN8rT4w",
  "redirect_uri": "com.example.ai://mimikey/callback",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

{
  "access_token": "3q2-7wEXAMPLEACCESSTOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "Zp9-EXAMPLEREFRESHTOKEN",
  "refresh_expires_in": 2592000,
  "grant_id": "6f1d2c3b-4a59-4e68-8b7c-9d0e1f2a3b4c",
  "account_id": "0b7e…",
  "vaults": [{ "vault_id": "8d4c…", "mode": 1 }],
  "client_type": "public",
  "account_identity_public_key": "9Xwg4YSHxLN9dr2JSRYL_wfRh_0iafGiNzQtT5blNys"
}

Important An authorization code is consumed by the first exchange attempt. After a failure such as a PKCE mismatch (invalid_grant) or a redirect mismatch, the same code cannot be reused; the user must authorize again.

Refresh:

The response matches the example above but omits vaults (a refresh never changes the grant's scope).

• Rotation: every refresh invalidates the refresh token it used and issues a new one, valid for 30 days from that refresh.
• Reuse detection: presenting an already-rotated refresh token returns 401 refresh_token_reused and immediately revokes every token of that grant. When you get this, stop retrying automatically and ask the user to authorize again.
• Refreshing does not require a signature, but the resulting access token is still useless without approval-key signatures.

#Revocation

#POST /api/oauth/revoke

Revokes the grant a token belongs to. Idempotent: an unknown token also returns { "ok": true }.

After revocation the grant's access and refresh tokens stop working immediately and every unfinished request becomes expired.

#Account

#GET /api/oauth/account

Signed call. Returns the authorizing user's account identity public key and the grant's vaults.

{
  "account_id": "0b7e…",
  "identity_public_key": "9Xwg4YSHxLN9dr2JSRYL_wfRh_0iafGiNzQtT5blNys",
  "vaults": [
    { "vault_id": "8d4c…", "name": null, "kind": "personal", "mode": 1 }
  ]
}

identity_public_key can be null if the account has not generated an identity key yet; update_item is not possible in that case.

#Requests

#The request object

POST /api/oauth/requests, PUT …/patch and GET /api/oauth/requests/{id} return the same object (creation returns a subset of fields):

#States and waiting

Pick, create and update requests have no approved intermediate state: acting on the card is the approval. Expiry is evaluated lazily on read: an unfinished request past its expires_at is reported as expired.

#POST /api/oauth/requests

Signed call. Creates a request.

A grant can have at most 100 unfinished requests (drafts included); beyond that the server returns 429 too_many_requests.

#pick_item

{ "op": "pick_item", "vault_id": null, "hint": { "url": "https://bank.example.com", "kind": "login" }, "reason": "Sign in to Example Bank to reconcile statements" }

{ "request_id": "a1b2c3d4-…", "state": "pending", "waiting_on": "user", "waiting_reason": "pick", "expires_at": "2026-10-23T08:40:00Z", "state_changed_at": "2026-10-23T08:30:00Z" }

Valid for 10 minutes. The user must pick even under the trust policy.

#get_item

Valid for 10 minutes. Starts as pending under ask and as approved under trust.

#create_item

{ "op": "create_item", "vault_id": "8d4c…", "kind": "login", "prefill": { "title": "Example Bank", "url": "https://bank.example.com/login", "username_hint": "me@example.com" }, "reason": "Sign in to Example Bank to reconcile statements" }

Valid for 30 minutes and always starts as pending. If the same grant and vault already have a pending create request for the same URL host, that request is returned with "existing": true.

#update_item

Do not include patch_enc at creation. The request is created as a draft (valid for 60 seconds and never shown on the user's devices); then upload the patch with PUT …/patch.

{ "op": "update_item", "vault_id": "8d4c…", "item_id": "3f6b8f7e-…", "fields": ["password"], "reason": "Password was changed on the website; sync it to MimiKey" }

{ "request_id": "a1b2c3d4-…", "state": "draft", "waiting_on": "client", "waiting_reason": "patch", "expires_at": "2026-10-23T08:31:00Z", "state_changed_at": "2026-10-23T08:30:00Z" }

#list_items

The result contains metadata only (no passwords or notes). The Swift SDK does not expose this operation.

#Upload an update patch

#PUT /api/oauth/requests/{id}/patch

Signed call. Uploads the sealed patch for an update_item request in the draft state. The request becomes pending and its expiry resets to 30 minutes.

Building the patch:

• Recipient: account_identity_public_key (or identity_public_key from GET /api/oauth/account)
• AAD: password-manager/oauth-patch/v1/{grant_id}/{request_id}
• Plaintext: {"patch":{"password":"new value"}}, containing only fields declared in fields

{ "patch_enc": "{\"format\":1,\"epk\":\"PHld72bS…\",\"envelope\":{\"format\":2,\"nonce\":\"8Ovm4dzX…\",\"ciphertext\":\"9eSfVW9L…\"}}" }

Returns the request object with state pending and waiting_reason review. Errors: invalid_patch (malformed or too large), request_not_found, 409 request_not_draft (not a draft, expired, or not an update_item).

#GET /api/oauth/requests/{id}

Signed call. Fetches a request, including its result once complete. Poll every 2 seconds, and check immediately when your app returns to the foreground.

{
  "request_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "state": "completed",
  "op": "pick_item",
  "vault_id": null,
  "item_id": null,
  "created_at": "2026-10-23T08:30:00Z",
  "expires_at": "2026-10-23T08:40:00Z",
  "state_changed_at": "2026-10-23T08:31:12Z",
  "waiting_on": null,
  "waiting_reason": null,
  "result_enc": "{\"format\":1,\"epk\":\"FiF4WQXs…\",\"envelope\":{…}}",
  "picked_item": { "id": "3f6b8f7e-…", "title": "Example Bank", "url": "https://bank.example.com/login", "kind": "login" }
}

Open result_enc with the seal private key and the AAD password-manager/oauth-result/v1/{grant_id}/{request_id}:

{
  "item": {
    "id": "3f6b8f7e-9c1d-4e2a-8b3c-4d5e6f7a8b9c",
    "revision": 4,
    "record": {
      "title": "Example Bank",
      "username": "me@example.com",
      "password": "correct horse battery staple",
      "url": "https://bank.example.com/login",
      "notes": "",
      "kind": "login",
      "extra": {},
      "updated_at": "2026-10-23T08:00:00.000Z"
    }
  }
}

A list_items result is { "v": 2, "items": [{ "id", "meta": { "title", "username", "url", "kind", "updated_at" } }] }.

#POST /api/oauth/requests/{id}/cancel

Signed call, no body. Cancels an unfinished request (draft, pending or approved). Returns { "request_id": "…", "state": "cancelled" }. A finished request returns 409 request_not_pending.

#Legacy mode 2 endpoints

These endpoints exist only for read-only compatibility with existing mode 2 grants; new grants cannot use them:

#Device-side endpoints

The MimiKey app calls these with the user's account session; integrators never use them:

#User grant management

#Operator: disabling an integrator

Available only to the platform operator, authenticated with a separate administrator session that is isolated from user sessions.

Disabling a client:

• revokes all of its grants, invalidates all of its tokens, and expires all of its unfinished requests;
• makes later signed calls return 401 client_disabled;
• makes authorize/info and authorize return 403 client_disabled, so the MimiKey apps refuse the client's deep links;
• is recorded in the administrator audit log.

enable only clears the flag; it does not restore revoked grants. Users must authorize again.