# Pocket ID: a passkey-only OpenID Connect provider you can run in Docker

> Pocket ID is a self-hosted OIDC and OAuth 2.0 provider that accepts only passkeys, aimed at people who find Keycloak or ORY Hydra heavier than their setup needs. The trade-off is real: there is no password fallback, and the README documents no recovery path.

**pocket-id/pocket-id** — The most user-friendly OpenID Connect Certified™ and OAuth 2.0 provider that lets users sign in to your applications with passkeys.

- Repository: https://github.com/pocket-id/pocket-id
- Website: https://pocket-id.org
- Stars: 9,328 · Forks: 313
- Language: Go
- License: BSD-2-Clause
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/pocket-id-pocket-id

## What Pocket ID solves, and for whom

Pocket ID is an OpenID Connect certified and OAuth 2.0 provider that authenticates users with passkeys instead of passwords. The README states the goal directly: to be simple and easy to use, in contrast to self-hosted providers like Keycloak or ORY Hydra, which the README calls "often too complex for simple use cases".

The audience follows from that framing. If you run a few self-hosted services and want one login for all of them, a full identity platform with realm configuration, user federation and policy engines is more surface area than the job requires. Pocket ID takes the opposite position: one credential type, passkeys, and no password field anywhere. The README's own example is a physical Yubikey used to sign in across self-hosted services.

The consequence is a hard boundary rather than a feature gap. A user without a passkey cannot sign in at all, and the README describes no password fallback or alternative credential. That is the design, not an omission to work around.

## How Pocket ID authenticates: passkeys, OIDC and the encryption key

Pocket ID sits between your applications and your users as a standard OIDC provider, so relying applications redirect to it, the user authenticates with a passkey, and the application receives the usual OIDC response. The README does not describe the internal token flow, so treat the protocol behaviour as the OIDC and OAuth 2.0 specification describes it rather than as something documented in the repository.

What the repository does show is the runtime shape. The backend is written in Go, and the top-level layout separates backend, frontend, docker, email-templates, scripts and tests. Configuration arrives through environment variables, and the .env.example file names two that must be set: APP_URL, the public address of your instance, and an encryption key. The encryption key can be given directly as ENCRYPTION_KEY or, in the method the file recommends, read from a file path in ENCRYPTION_KEY_FILE.

The optional variables in the same file hint at deployment concerns rather than features: TRUST_PROXY for running behind a reverse proxy, MAXMIND_LICENSE_KEY, and PUID and PGID for file ownership on the mounted data directory. Email templates ship in the repository, which implies mail is part of some flows, but the README does not document which ones.

## Installing Pocket ID with Docker Compose

The README says the easiest and recommended way to set up Pocket ID is Docker, and points to the documentation for the full guide. The repository ships a docker-compose.yml you can use as the starting point.

The service definition pins the v2 image tag, mounts ./data into /app/data, and publishes port 1411. The image is available as pocketid/pocket-id:v2 or ghcr.io/pocket-id/pocket-id:v2, and the file also includes an optional healthcheck that runs the binary's own healthcheck subcommand.

```yaml
services:
  pocket-id:
    image: pocketid/pocket-id:v2 # or ghcr.io/pocket-id/pocket-id:v2
    restart: unless-stopped
    env_file: .env
    ports:
      - 1411:1411
    volumes:
      - "./data:/app/data"
    healthcheck:
      test: [ "CMD", "/app/pocket-id", "healthcheck" ]
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s
```

Configuration comes from the .env file referenced by env_file. The example file marks APP_URL as required and shows how to generate a key for the direct method.

```bash
openssl rand -base64 32
```

Put the result in ENCRYPTION_KEY, or write it to a file and set ENCRYPTION_KEY_FILE to that path instead. Then start the stack.

```bash
docker compose up -d
```

The container should come up on port 1411, and the healthcheck should report healthy after its start period. The README stops short of describing the first-run screen, so what you see in the browser after that is not something this article can tell you.

## The passkey-only decision is the main limitation

Every identity provider makes you choose between convenience and recovery. Pocket ID chooses convenience and pushes the recovery problem onto the user's devices. If someone loses the phone or security key holding their passkey, the README describes no account recovery flow, and there is no password to fall back on. The documentation linked from the README is the place to check whether recovery exists; the README itself is silent on it.

The same applies to the encryption key. The .env.example calls the direct ENCRYPTION_KEY method simple but less secure and recommends the file-based variant, which tells you the key matters to whatever Pocket ID encrypts at rest. Losing it is not a configuration mistake you can shrug off, and the repository does not describe a rotation or re-import procedure.

There is also a fit question. Pocket ID is the wrong tool if you need to support users who will not or cannot register a passkey, if you need to authenticate non-human clients with a policy engine, or if your organisation requires password-based break-glass access. Those are not gaps the project intends to close. They are reasons to pick something else.

## Pocket ID compared with Keycloak and Authentik

The README names Keycloak and ORY Hydra as the complex alternatives Pocket ID is reacting to, and the search data shows people comparing it with Authentik, Authelia, Zitadel and Tinyauth as well. The difference is scope, not quality.

Keycloak is a general identity platform: realms, user federation, role mapping, and a long list of configurable flows. Pocket ID has one authentication method and a small set of environment variables. Authentik sits closer to Keycloak in that it offers flows, stages and policy bindings you can compose. If your requirement is "one login for my services, using passkeys", the smaller surface is the point. If your requirement is "different authentication rules per application group", the smaller surface is the obstacle.

Tinyauth is the closer comparison in spirit, since both target self-hosters who want something lighter than a full platform. The README does not compare the two, so the honest statement is that Pocket ID's distinguishing claim is passkey-only authentication plus OpenID Connect certification, and the certification is the part you can verify independently through the OpenID Foundation's list of certified providers.

## Maintenance, upgrades and the BSD-2-Clause licence

Pocket ID is not archived, and the last push to the repository was on 2026-09-08. Releases have been frequent: v2.12.0 on 2026-07-29, v2.13.0 on 2026-08-07, and v2.14.0 on 2026-08-18. The repository carries a CHANGELOG.md and a .goreleaser.yaml, so upgrade notes have a place to live.

Upgrading is a tag change in the compose file, since the image reference is pocketid/pocket-id:v2. That tag tracks the major version rather than a fixed release, which means pulling the image can move you forward without you editing anything. If you want upgrades to be deliberate, pin a specific version tag instead and read CHANGELOG.md before moving. The README does not document a rollback procedure, so the thing to verify before an upgrade is that your ./data directory is backed up and that the encryption key is stored somewhere other than the container.

The licence is BSD-2-Clause, a permissive licence. It permits use and redistribution with the copyright notice and licence text retained. This is not legal advice; if you redistribute Pocket ID or embed it in a product, read the LICENSE file in the repository and get your own advice.

## Conclusion

Pocket ID fits a self-hoster who wants passkey sign-in for a handful of services and is willing to accept that passkeys are the only credential. It does not fit anyone who needs a password fallback, a documented account recovery flow, or fine-grained policy that goes beyond basic OIDC. Before adopting it, verify two things in your own deployment: that the ENCRYPTION_KEY survives container restarts, and that every user has a second passkey registered on a different device.

## FAQ

### What is Pocket ID?

It is an OpenID Connect certified and OAuth 2.0 provider that lets users sign in to applications with passkeys instead of passwords. The README describes its goal as being simple and easy to use, in contrast to providers like Keycloak or ORY Hydra.

### How do I install Pocket ID?

The README says the easiest and recommended way is Docker and points to the documentation for the setup guide. The repository includes a docker-compose.yml that pins the pocketid/pocket-id:v2 image, mounts ./data into /app/data, and publishes port 1411.

### Is Pocket ID secure?

It authenticates only with passkeys, so there is no password to phish or reuse, and it is listed as an OpenID Connect certified provider. The repository does not document account recovery, so the practical risk is losing the device that holds a user's passkey.

### Which is better, Pocket-ID or Authentik?

Pocket ID is smaller and passkey-only, while Authentik is closer to a general identity platform with configurable flows and policies. If you need one passkey login for a few self-hosted services, Pocket ID's smaller surface is the point; if you need per-application authentication rules, it is the obstacle.

### How long does a Pocket ID session last?

The README and the .env.example file do not document session lifetime or a session configuration variable. The documentation linked from the README is the place to check.

## Sources

- [License: BSD-2-Clause](https://github.com/pocket-id/pocket-id/blob/main/LICENSE)
- [pocket-id/pocket-id on GitHub](https://github.com/pocket-id/pocket-id)
- [Project website](https://pocket-id.org)
- [README](https://github.com/pocket-id/pocket-id/blob/main/README.md)
- [Releases](https://github.com/pocket-id/pocket-id/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pocket-id-pocket-id