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.basic | GET /integration/me: email and an app-specific subject |
|---|---|
secret.request | POST /integration/secret-requests |
secret.receive | GET /integration/secret-requests/{id} |
shared.items.read | GET /integration/shared-items |
events.read | GET /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).
- Verify the Ed25519 signature with
device.sign_public_keyovercanonical("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. - 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 decryptctwithnonceand the same info bytes as AAD → 32-byte content key. - Decrypt the ciphertext after
v1.with AES-256-GCM, the content key andnonce, AAD =canonical("pm|integration-response|v1", request_id, client_id, request_nonce). - Check that
request_id,client_idandrequest_nonceinside the JSON match, then usefields. Do not log them.
6. Other endpoints
GET /integration/me→{"subject": "…", "email": "user@example.com"}GET /integration/shared-items→ approvals still available to youGET /integration/events→ your activity for this user (metadata only)
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 limits | per second, minute, hour and day from your plan, plus a concurrent-request limit (429 rate_limited, Retry-After) |
|---|---|
| Billable operation | one 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. |
| Quota | included operations per month (429 quota_exceeded with reset time); usage alerts by email at 80, 90 and 100 % |
| Storage | encrypted responses held for you count against your storage limit; when full, new requests are refused (quota_exceeded) and nothing is deleted |
| Payload / page size | request body and ?limit= are capped by your plan (413 payload_too_large) |
/oauth/token, /oauth/revoke | 30 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
- Confidential (server) apps get client secrets, shown once; we store only a hash. Rotate by creating a new secret, deploying it and revoking the old one. Native/mobile apps register as public clients: no secret, PKCE only.
- Webhooks (
secret_request.approved,.denied,.revoked) go to https URLs on public addresses only, carry ids and statuses (never secrets) and are signed:PM-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>. Retries are bounded. - Sandbox apps can only be connected to your own account; use synthetic items. There is no API explorer against real users' vaults.
- Machine-readable reference: OpenAPI 3.1.