The PassIsland API
Everything a script or third-party tool can do on your behalf, using a personal access token instead of your master password. This is the reference for calling it directly — there's no SDK yet, just plain HTTP and JSON.
https://api.passisland.replatform.co ·
every endpoint below is under /v1.Quickstart
Two minutes from nothing to a working request.
-
Generate a token
Sign in to PassIsland, open Settings → Developer access, and generate one. Give it a label, pick the scopes it needs, and set an expiry. The full token —
pisl_live_…— is shown exactly once, at creation. Store it like a password, because it effectively is one. -
Call an endpoint
curl https://api.passisland.replatform.co/v1/account/me \ -H "Authorization: Bearer pisl_live_..." -
That's the whole authentication story
One header, no separate exchange step, no expiry to refresh day-to-day — a personal access token is a complete, self-contained credential. It's also, deliberately, not a way to sync vault data. See why below before you go looking for that endpoint.
The device-trust boundary
A personal access token has no device behind it, and vault access requires one.
PassIsland's vault sync isn't just password-protected — it's device-protected. A new device has to be individually approved by a device you already trust before it can pull vault ciphertext or key envelopes (that's the whole point of the "Approve this device" flow you see when you sign in somewhere new). That approval hands the new device a copy of your vault key, wrapped so only it can open it.
A personal access token can't participate in that ceremony — it's a string, not a device with
a keypair — so it structurally cannot be handed a vault key. Rather than invent a "vault" scope
and rely on nobody ever granting it by mistake, the vault routes
(/v1/vaults/*) don't even parse a token-shaped credential: they only ever look for
the session cookie a signed-in device carries. There is no misconfiguration that exposes vault
content to a token, because the code path that reads a token isn't wired to those routes at all.
What's left — account info and device management — is exactly what's safe to automate: enough for a backup script to confirm your account is in good standing, or a security tool to revoke a lost laptop, without ever being able to read a single saved password.
Personal access tokens
Created and revoked from the web app only — POST /v1/tokens and
DELETE /v1/tokens/:id both require a signed-in session, not another token. That's
deliberate: a compromised token must not be able to mint itself a longer-lived replacement or a
wider one.
| Property | |
|---|---|
| Format | pisl_live_ + 64 hex characters |
| Lifetime | Whatever you set at creation — 30 days, 90 days, a year, or never (not recommended) |
| Storage | Only a SHA-256 hash is kept server-side. Lose the plaintext and the only fix is revoking it and creating a new one. |
| Transport | Authorization: Bearer pisl_live_.... Never a cookie, never a query parameter. |
api.passisland.replatform.co returns none, so a browser
can't call it cross-origin even by accident.Scopes
A token can carry any combination of these three — nothing more exists.
/v1/account/me: email, verification status, member-since date. No password, no security answers.GET /v1/devices.API reference
/v1/account
{
"accountId": "acct_...",
"email": "you@example.com",
"emailVerified": true,
"status": "active",
"hasVault": true,
"entitlement": "free",
"createdAt": "2026-01-14T09:02:11.000Z",
"itemLimit": 5,
"itemCount": 3,
"adminRole": null
}itemLimit is the maximum number of saved passwords this account may have at once — creating one
more once itemCount reaches it is refused with 403 item_limit_reached until an old one
is removed. adminRole is null for almost everyone; it reflects a role grant on the
platform, not something this API lets you set.
/v1/devices
Every device on the account — name, platform, status, last seen. Public keys are included; there is nothing secret in a device record.
Ends that device's sessions immediately. Doesn't erase anything already cached on the device locally.
Removes a revoked (or never-approved) device from the list permanently. Refuses on an active device — revoke it first.
Rejected outright for a token, always — see why no vault scope. Approving a device needs the vault key in memory to wrap it for the new device.
/v1/tokens
Your tokens' labels, scopes, and timestamps — never the value itself. There is no endpoint that returns a token's plaintext after creation.
Create one. Returns the plaintext exactly this once.
{ "label": "backup script", "scopes": ["account:read"], "expiresInDays": 90 }
// → { "id": "pat_...", "token": "pisl_live_..." }Revokes immediately. Anything using it starts failing with 401 unauthenticated on its very next call.
/v1/vaults — not reachable by token
Bootstrap, push/pull revisions, recovery, and the master-password change all live under
/v1/vaults/*. They accept only the session cookie a signed-in device holds — a
Bearer header is simply never inspected there. This isn't an authorization check
that could be misconfigured; the routes and the token-resolving code aren't connected at all.
Errors
Every error is JSON: {"error": {"code": "...", "message": "..."}}.
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated | Missing, malformed, expired, or revoked token — or no session cookie for a session-only route. |
| 403 | insufficient_scope | The token is valid but doesn't carry the scope this endpoint needs. |
| 403 | session_required | This action can only be done signed in — a token is refused outright, not just under-scoped. |
| 403 | csrf_failed | Session auth on a state-changing request without a valid CSRF token. Doesn't apply to token auth. |
| 400 | invalid_request | Missing or wrong-shaped field — see the message for which. |
| 404 | not_found | Including a token or device id that exists but belongs to someone else — never distinguished from "doesn't exist." |
| 429 | rate_limited | Too many attempts in the current window. Back off and retry later. |
Rate limits & security
- A token's activity updates its "last used" timestamp on every successful call, visible next to it in Settings — the easiest way to notice one that's still active somewhere you didn't expect.
- Revoking a token takes effect immediately and everywhere; there's no cache to wait out.
- No CORS headers are returned by this API — it's server-to-server. A token belongs in a backend environment variable or secrets manager, never in code that ships to a browser.
- Scopes are additive and capped at what exists today —
account:read,devices:read,devices:manage. A vault-access scope isn't a future addition; see why no vault scope.