Sign in to plamotrack with a passkey through Pocket ID

Pocket ID is a small, self-hosted OpenID Connect provider that signs you in with a passkey instead of a password. Pair it with plamotrack’s OIDC mode and you get passkey sign-in, plus OAuth links for Claude.ai and the other web assistants, without an account at Google or any other cloud provider. Pocket ID is an optional, supported provider from v0.6.0-alpha. It needs nothing special from plamotrack: one client in Pocket ID and the usual OIDC settings in .env.

Pocket ID is a second service you run and back up alongside plamotrack. If you already have a Google account you’re happy to sign in with, the OIDC page is less to maintain.

What you need

Its own hostname, such as id.example. Pocket ID can’t live under a path of another site.
HTTPS on that hostname. Passkeys only work on a secure origin. If you followed VPS + Caddy, a second site block in the same Caddyfile does it.
A persistent volume for Pocket ID’s data.
An ENCRYPTION_KEY for Pocket ID, kept with your backups. It encrypts Pocket ID’s signing keys; without it, a restore won’t start.
plamotrack itself on an https:// address, as OIDC mode requires.

Choose Pocket ID’s hostname once. Every passkey is tied to it, so changing the hostname later leaves every passkey unusable.

Run Pocket ID

This is the setup plamotrack was tested with: Pocket ID v2.16.0 on the same host, behind Caddy. Pocket ID’s own documentation covers its other options.

Generate an encryption key

In a new directory for Pocket ID, create a .env file that only you can read, holding a random key:

echo "ENCRYPTION_KEY=$(openssl rand -base64 32)" > .env && chmod 600 .env

Copy this key to wherever you keep plamotrack’s .env backup.

Create docker-compose.yml

In the same directory, create docker-compose.yml, using your own hostname:

services:
  pocket-id:
    image: ghcr.io/pocket-id/pocket-id:v2.16.0
    restart: unless-stopped
    environment:
      APP_URL: https://id.example
      TRUST_PROXY: "true"
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
    ports:
      - "127.0.0.1:8081:1411"
    volumes:
      - data:/app/data
volumes:
  data:

APP_URL is the bare hostname, with no path. The port is published on loopback only, so Caddy is the only way in.

Add Pocket ID to Caddy

Add a site block for the new hostname to /etc/caddy/Caddyfile, beside plamotrack’s:

id.example {
    reverse_proxy 127.0.0.1:8081
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
}

Use the same certificate path as plamotrack’s own site block. The block above is the DNS-01 one, the tested path. If you use Caddy’s default HTTP challenge instead (the host is reachable on ports 80 and 443, as VPS + Caddy describes), delete its tls { … } block: without the Cloudflare module, Caddy refuses a Caddyfile that names it, and that would stop plamotrack’s site too.

Restart Caddy

sudo systemctl restart caddy

Start Pocket ID

docker compose up -d

Open https://id.example/.well-known/openid-configuration. The issuer it shows is the value plamotrack needs — the bare https://id.example, with no trailing slash.

Create your account and a passkey

Create your user in Pocket ID as its documentation describes. This account becomes the owner of your plamotrack instance. To sign in to Pocket ID without a passkey — the first time, or on a new device — get a one-time login code from Pocket ID’s directory on the host:

docker compose exec pocket-id /app/pocket-id one-time-access-token <your-username>

Sign in with it, then add a passkey from your account settings in Pocket ID. A passkey saved to a password manager that syncs works on your phone as well as your computer.

Pocket ID’s own access log records a login code in the request path when the code is used. Codes are single-use and short-lived, but treat that log as sensitive and don’t share it.

Create the plamotrack client in Pocket ID

plamotrack needs one client in Pocket ID. It carries both the browser login and the OAuth links for AI assistants.

Add an OIDC client

In Pocket ID’s admin area, add a new OIDC client named plamotrack.

Enter both callback URLs

Add both of these, using your plamotrack address:

https://plamotrack.example/api/auth/oidc/callback — the browser login
https://plamotrack.example/mcp/auth/callback — AI assistants

Keep it confidential, with PKCE

Leave the client confidential (not public), and turn PKCE on.

Let your account use it

A client created in Pocket ID’s admin area is restricted to user groups by default, so no one can sign in through it yet. Add your account to a group the client allows.

Note the client ID and secret

Copy the client ID and create a client secret. You’ll need both in plamotrack’s .env.

You don’t register plamotrack’s /mcp with Pocket ID in any other way. Assistants register with plamotrack, not with Pocket ID, so Pocket ID only ever sees this one client.

Update plamotrack’s `.env`

Add these to plamotrack’s .env, then restart the stack:

AUTH_MODE=oidc
PUBLIC_BASE_URL=https://plamotrack.example
OIDC_ISSUER=https://id.example                # exactly as Pocket ID's discovery document states it
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
MCP_OAUTH_SIGNING_KEY=<64 hex chars>          # run: openssl rand -hex 32

docker compose up -d

Claim the instance

The first sign-in works as on the OIDC page:

Enter the setup token

Open plamotrack and enter the one-time setup token from the API log.

plamotrack sends you to Pocket ID. Sign in with your passkey.

Allow plamotrack

The first time, Pocket ID asks you to let plamotrack see your email and profile. Allow it. Pocket ID remembers the answer.

Your Pocket ID account is now the owner. Any other Pocket ID user who tries to sign in is refused, and the refusal is recorded in the audit log.

Link an AI assistant

Connect Claude.ai, ChatGPT, Gemini Spark or Mistral as described in Web clients (OAuth). When the assistant sends you to sign in, you sign in at Pocket ID with your passkey. Pocket ID has to be reachable from your browser and from the plamotrack host. It doesn’t have to be reachable from the internet: the assistant talks only to plamotrack, and plamotrack talks to Pocket ID on its behalf. This was tested with Claude.ai and a Pocket ID on a private network.

Back up Pocket ID

Back up Pocket ID alongside plamotrack’s backups. Without Pocket ID’s data you can’t sign in, and without its ENCRYPTION_KEY that data is useless: under a different key, Pocket ID doesn’t start. Pocket ID marks its export as experimental.

Export Pocket ID's data

From Pocket ID’s directory on the host:

docker compose exec -T pocket-id ./pocket-id export --path - > pocket-id-export.zip

Keep the export private

chmod 600 pocket-id-export.zip

Keep Pocket ID's .env with it

Copy Pocket ID’s .env, which holds the ENCRYPTION_KEY, to the same place as the export.

Restore Pocket ID

Put the .env back

Copy the saved .env into Pocket ID’s directory on the host.

Import the export into a fresh volume

docker compose run --rm -T pocket-id ./pocket-id import --yes --path - < pocket-id-export.zip

Start Pocket ID

docker compose up -d

A restore keeps your passkeys. It also keeps your account’s identity, so you are still the owner of plamotrack. Assistants linked before the backup stay linked.

If you lose your passkey

Losing a passkey doesn’t change your identity, so plamotrack needs no recovery step.

Get a login code

Run this from Pocket ID’s directory on the host.

docker compose exec pocket-id /app/pocket-id one-time-access-token <your-username>

A login code needs a Pocket ID admin or a shell on the host. On a single-owner install the only admin is usually you, so if you lose your only passkey and can’t reach the host, you can’t get back in. Keep a passkey in a password manager that syncs, or register a second one.

rebind-oidc, on the OIDC page, is only for moving the instance to a different account or provider.

Revoking an assistant is local to plamotrack

Pocket ID has no endpoint for revoking tokens. When a link ends at plamotrack — the assistant revokes it, or you run rebind-oidc — plamotrack ends it at once, but it has nothing to call at Pocket ID. The refresh token Pocket ID issued for that link stays valid at Pocket ID until it expires — 30 days by default. plamotrack never accepts it again, so the assistant stays disconnected. Nothing for you to do.

Upgrading from an earlier release

Before v0.6.0-alpha, linking an assistant through Pocket ID only worked if you had registered your instance’s /mcp as an API in Pocket ID. That’s no longer needed.

Upgrade plamotrack

Update as described in Upgrading.

Delete the API registration

In Pocket ID’s admin area, delete the API you registered for your instance’s /mcp.

Reconnect each assistant once

Each assistant linked that way asks you to reconnect once. Reconnecting is the ordinary link: sign in at Pocket ID and you’re done. Claude.ai asked even for a connector that had been removed and added again.

Get Started

Using plamotrack

Deployment

Authentication

AI & MCP

Configuration & Maintenance

Sign in to plamotrack with a passkey through Pocket ID

What you need

Run Pocket ID

Create your account and a passkey

Create the plamotrack client in Pocket ID

Update plamotrack’s `.env`

Claim the instance

Link an AI assistant

Back up Pocket ID

Restore Pocket ID

If you lose your passkey

Revoking an assistant is local to plamotrack

Upgrading from an earlier release

​What you need

​Run Pocket ID

​Create your account and a passkey

​Create the plamotrack client in Pocket ID

​Update plamotrack’s .env

​Claim the instance

​Link an AI assistant

​Back up Pocket ID

​Restore Pocket ID

​If you lose your passkey

​Revoking an assistant is local to plamotrack

​Upgrading from an earlier release

What you need

Run Pocket ID

Create your account and a passkey

Create the plamotrack client in Pocket ID

Update plamotrack’s `.env`

Claim the instance

Link an AI assistant

Back up Pocket ID

Restore Pocket ID

If you lose your passkey

Revoking an assistant is local to plamotrack

Upgrading from an earlier release