Password Manager

Developer documentation

Last updated 4 October 2026

Base URL https://password-manager.in/api/v1/ · JSON · HTTPS only. All examples use synthetic values.

1. Register an application

Sign in to a Password Manager account (email code) to obtain an account token, then:

POST /developer/apps
Authorization: Bearer <account token>

{"name": "ABC Accounting",
 "company": "ABC Accounting Pvt Ltd",
 "website": "https://accounting.example.com",
 "description": "Files GST returns with credentials the client approves.",
 "redirect_uris": ["https://accounting.example.com/oauth/callback"],
 "enc_public_key": "<base64url X25519 public key, 32 bytes>",
 "requested_scopes": ["identity.basic", "secret.request", "secret.receive"]}

The response contains your client_id, status: "pending", the key fingerprint and your client_secret, shown once. Nothing works until an administrator approves the app. GET /developer/apps lists your apps; DELETE /developer/apps/{id} deletes one and revokes all its tokens and approvals.

Redirect URIs must be absolute https URLs (or http://localhost/127.0.0.1 for development) without wildcards or fragments, and are matched exactly.

2. Scopes

identity.basicGET /integration/me: email and an app-specific subject
secret.requestPOST /integration/secret-requests
secret.receiveGET /integration/secret-requests/{id}
shared.items.readGET /integration/shared-items
events.readGET /integration/events

3. OAuth 2.1 with PKCE

Create a code_verifier (43–128 characters of A-Z a-z 0-9 . _ ~ -) and code_challenge = base64url(SHA-256(code_verifier)) without padding, then send the user to:

https://password-manager.in/oauth/authorize?response_type=code
  &client_id=pmc_example&redirect_uri=https%3A%2F%2Faccounting.example.com%2Foauth%2Fcallback
  &scope=identity.basic%20secret.request%20secret.receive
  &state=<random>&code_challenge=<challenge>&code_challenge_method=S256

The user signs in with an email code and taps Allow or Deny. You receive ?code=…&state=… (check state) or ?error=access_denied. Unknown clients or redirect URIs are never redirected to.

Exchange the code within 5 minutes (single use):

POST /oauth/token
{"grant_type": "authorization_code", "code": "<code>",
 "redirect_uri": "<same URI>", "client_id": "pmc_example",
 "client_secret": "pms_example", "code_verifier": "<verifier>"}

→ {"access_token": "pma_…", "token_type": "Bearer", "expires_in": 900,
   "refresh_token": "pmr_…", "scope": "identity.basic secret.request secret.receive"}

Refresh with {"grant_type": "refresh_token", "refresh_token": "pmr_…", client credentials}. Each refresh token works once; presenting a used one revokes the whole token family. Revoke with POST /oauth/revoke {"token": "…", client credentials}. HTTP Basic client authentication is also accepted.

4. Request a secret

POST /integration/secret-requests
Authorization: Bearer pma_…

{"purpose": "GST portal credential",
 "fields": ["username", "password"],
 "nonce": "<16-64 chars [A-Za-z0-9_-], unique>",
 "expires_in": 600}

Fields: username, password, notes, website, pin, card, otp. The user chooses the item, may untick fields, and picks once, 10m or until_revoked. Requests expire after expires_in seconds (60–600); at most 5 can be pending per user; a reused nonce returns 409 replayed_nonce.

Poll GET /integration/secret-requests/{id} a few seconds apart. Status: pending, approved (with response), delivered (a once answer already fetched), denied, expired, revoked. Webhooks are not available yet.

5. Decrypt the response

"response": {"v": 1,
  "ciphertext": "v1.<base64url>", "nonce": "<base64url 12 bytes>",
  "wrapped_key": "v1.<base64url(JSON {epk, salt, nonce, ct})>",
  "signature": "<base64url Ed25519>",
  "device": {"id": "…", "enc_public_key": "…", "sign_public_key": "…", "key_signature": "…"}}

canonical(label, parts): for the label and then each part, a 4-byte big-endian length followed by the bytes (text as UTF-8; digests as raw bytes).

  1. Verify the Ed25519 signature with device.sign_public_key over canonical("pm|integration-sig|v1", request_id, client_id, request_nonce, nonce, SHA-256(ciphertext), SHA-256(wrapped_key)), where the two hashes are over the exact strings received. Pin the device key per user on first use and alert if it changes.
  2. Unwrap: X25519(your private key, epk) → HKDF-SHA256 (salt = salt, info = canonical("pm|integration-key|v1", request_id, client_id), 32 bytes) → AES-256-GCM decrypt ct with nonce and the same info bytes as AAD → 32-byte content key.
  3. Decrypt the ciphertext after v1. with AES-256-GCM, the content key and nonce, AAD = canonical("pm|integration-response|v1", request_id, client_id, request_nonce).
  4. Check that request_id, client_id and request_nonce inside the JSON match, then use fields. Do not log them.

6. Other endpoints

7. Expiry and revocation

Access tokens last 15 minutes, refresh tokens 30 days. Users can revoke a single approval or disconnect your app; administrators can suspend apps. Afterwards tokens return 401 invalid_token and stored answers are erased.

8. Subscriptions, limits, metering and errors

Every integration call needs an approved app, an active API subscription (checked at request time) and a scope included in your plan. Limits are enforced on the server across all apps and credentials of one subscription; a new credential never resets them. Windows are UTC; the billable quota resets at 00:00 UTC on the 1st of each month.

Rate limitsper second, minute, hour and day from your plan, plus a concurrent-request limit (429 rate_limited, Retry-After)
Billable operationone successfully created POST /integration/secret-requests (201). Not billed: validation errors, replays, limit refusals, server errors, status polling, reads. Send Idempotency-Key to retry safely.
Quotaincluded operations per month (429 quota_exceeded with reset time); usage alerts by email at 80, 90 and 100 %
Storageencrypted responses held for you count against your storage limit; when full, new requests are refused (quota_exceeded) and nothing is deleted
Payload / page sizerequest body and ?limit= are capped by your plan (413 payload_too_large)
/oauth/token, /oauth/revoke30 per minute per client and IP (abuse protection)

Errors are JSON without stack traces: {"ok": false, "code": "…", "message": "…"} — invalid_token (401), subscription_required / subscription_expired (402), insufficient_scope / scope_denied (403), not_found (404), replayed_nonce (409), validation (422), rate_limited / quota_exceeded / too_many_pending (429), accounting_unavailable / service_paused (503). Token endpoint errors use OAuth format.

9. Credentials, public clients and webhooks

Download for Android