# Passport: verifiable credentials and a social model of identity

> Passport is an identity verification application in which people grow personal collections of verifiable credentials and organisations assess identities against them, backed by a Postgres database hosted by Passport XYZ, the Ceramic network and onchain attestations across about a dozen networks. It is a Yarn and Lerna monorepo with TypeScript services, and the last push was on 2026-10-15.

**passportxyz/passport** — Passport allows users to prove their identity through a secure, decentralized UI

- Repository: https://github.com/passportxyz/passport
- Stars: 2 · Forks: 0
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/passportxyz-passport

## The argument against both centralised and self-sovereign identity

Passport allows users to prove their identity through a secure, decentralized UI, and the reasoning behind that is worth reading because it explains the architecture.

The problem it starts from is that many social organisations, online in particular, have difficulty ensuring that every participant is a unique human and does not have multiple participating accounts. The existing answers fall into two camps. Most digital identity solutions are either centralised, like national identity cards, or individualistic, like most self-sovereign identity models.

The claim is that identity is naturally intersectional and social. Everybody shares different data and relationships with a unique set of others. Passport aims to provide a more collaborative and secure infrastructure for digital identity by capturing the richness of our diversely shared lives.

That is a real difference in model, and it explains the rest of the design. A centralised model gives you one issuer's view of you. A conventional self-sovereign model gives you a wallet of your own claims, with no help deciding which of them a counterparty should find persuasive. A social model is a network of institutions each issuing credentials about the people and organisations they know, and a verifier assembling a picture from several of them.

The project is explicit that it is an identity verification application. People grow personal collections of verifiable credentials about themselves, and organisations assess identities to coordinate rights and responsibilities. The institutions define, verify and utilise identity as functions of the networked records of the individuals.

The project is also explicit about its scope. While it builds Passport agnostic to specific applications, it is actively exploring the benefits for personhood proofs and for plurality in organisational designs, with links to both concepts.

The documentation is at docs.passport.xyz, and the last push was on 2026-10-15 with the most recent release v1.0.104 from 2026-09-22.

## Three data sources, and one of them is a service you have to run yourself

The data section is the part of the documentation that tells you what it actually takes to get a working instance, and it is not one source but three.

The first is a Postgres database hosted by Passport XYZ. To run the Passport application locally you need to spin up the Passport Scorer API, which is a separate repository, and the instructions for it are in its own setup documentation. The sample environment variables in the `.env-example.env` files are configured to make requests to the scorer API running locally, and once the scorer API is running locally you have a reliable data source for development.

That is a significant dependency for a local run. The application is not self-contained in its own repository; the data path goes through a separate service that you are expected to start yourself.

The second source is the Ceramic network, and here the situation is the opposite. No steps are needed to run the Ceramic network locally, and the sample environment variables are configured to make requests to a test version of it.

The third location is onchain attestations made across about a dozen different networks, with details referenced through an attestation explorer.

So a local development environment has three different trust postures: a local API you run, a public test network you do not, and a set of public chains you do not. The Ceramic part of that is also the part with the least control, since a test network can be reset under you and the onchain attestations are, by definition, permanent.

The background knowledge the project lists as a prerequisite is worth repeating, because it is an unusual admission for a README. You need to know what a wallet is and how to create one, what a Verifiable Credential is, and the basics of the Ceramic network, specifically interacting with DIDDatastore and Self.ID.

## A Yarn workspace with eight packages and a build order

The `package.json` at the root shows this is a Yarn workspaces monorepo managed with Lerna, and the package list and the build script together describe the dependency order.

The workspaces are `app`, `database-client`, `iam`, `embed`, `identity`, `types`, `platforms` and `embed-popup`. The build script runs them in a fixed sequence: `yarn build:platforms && yarn build:identity && yarn build:database-client && yarn build:iam && yarn build:embed && ...`, which is the shape of a monorepo where later packages depend on earlier ones.

The package names still carry the Gitcoin lineage, `@gitcoin/passport` and `@gitcoin/passport-iam`, `@gitcoin/passport-identity`, `@gitcoin/passport-app`, `@gitcoin/passport-platforms`, in the workspace-scoped lint and test scripts. The project moved to the passportxyz organisation but the package names did not, and for anyone referencing these packages that is the detail that matters.

What each package does is described in the readme. The `app` is the web app allowing users to interact with their Passport. The `iam` is the server handling incoming requests to issue credentials and process verifications, which is the trust boundary of the whole system. The `identity` package is a helper to compile Spruce DIDKit and export its functions for use in the `iam` and `app` packages, which is how the verifiable credential primitives reach the application. The `database-client` holds database connection implementations and currently supports the Ceramic network. The `schemas` package holds Ceramic schemas and model definitions with scripts for creating and publishing them to the Ceramic network, and `types` holds shared type definitions.

Two more directories sit alongside the packages. `infra` holds the Pulumi deployment configuration for the repository, so the deployment is code rather than a runbook, and `js-ceramic/` and `hn-signer/` are the other top-level directories in the tree.

The tooling is a conventional modern TypeScript setup with eslint 9, typescript-eslint, prettier with an eslint integration, husky 7 with lint-staged, and commitlint with the conventional config, which is enforced through a `commitlint.config.js` at the root.

## Running it locally, and the parts you will have to read twice

The quick start is short, and the environment file step is the one that catches people.

The prerequisites are Node v20 LTS, Yarn and Git, and the install is a clone, a global lerna and a yarn install:

```sh
git clone https://github.com/passportxyz/passport.git
cd passport
npm install --global lerna
yarn install
```

Then the environment files, copied from the examples and edited:

```sh
cp ./app/.env-example.env ./app/.env
cp ./iam/.env-example.env ./iam/.env
```

Then `yarn start` to start the iam, app and ceramic services concurrently, with the comment reminding you to create the env files first, and separately the Passport Scorer API has to be running locally, following its own setup instructions.

So the local stack is four things: the app, the iam, ceramic, and the scorer API. Three of them come up from this repository with one command and the fourth does not.

The install script at the root of the repository, `install.sh`, and the two Playwright dependency scripts, `debian-install-playwright-deps.sh` and `fedora-install-playwright-deps.sh`, indicate that browser automation is part of the test story, and the `.mcp.json` file at the root, alongside the `.agents/`, `.claude/` and `.cursorrules` files, shows the same agent-facing configuration pattern that has become common in this kind of repository.

## A contribution process with two approvals and a squashed merge

The reviewing changes section is unusually detailed for a README, and it reads like a constitution rather than a formality.

Once a pull request is sent, the Passport team reviews it. All pull requests must be approved by two committers before being merged. If changes are necessary, the team leaves comments requesting them, and the documentation is candid that a pull request cannot be guaranteed to be merged even when modifications are requested, because the team re-evaluates the contribution as it changes.

That last point is the interesting one. It is an explicit statement that review can be withdrawn, which is unusual to state plainly and worth understanding before you invest a week in a large contribution.

The rest of the process is conventional and well described. Committers may push style changes directly to your branch, and if you would rather manage all changes yourself you can disable the Allow edits from maintainers feature when submitting. The team may optionally assign someone to review a pull request, and if someone is assigned they must explicitly approve the code before another team member can merge it. When the review finishes the pull request is squashed and merged, with the escape valve that if you have carefully organized your commits and believe they should be merged without squashing you should mention it in a comment.

The squashing default has a practical consequence for contributors who have structured their history deliberately, and the documentation at least tells you how to make your case.

The project welcomes contributions to both Passport and the Scorer API, asks reviewers to read the contributing guidelines first, points at a Discord with a builder role for getting help, and publishes a near term roadmap as a GitHub project backlog.

## Where Passport is the wrong choice

The first case is a team that wants a turnkey identity product. This is an application and a service stack with a Postgres database hosted by Passport XYZ, an IAM server, a Ceramic-backed data client and onchain attestations. If you want something you can deploy and hand to a product team, this is an amount of infrastructure to assemble, and the scorer API dependency is not optional for the local data path.

The second case is a project that needs the identity model to be simple. A wallet of your own claims, presented to a verifier, is a smaller thing to reason about than a network of institutions each holding credentials about you. The trade is real and it is the one the project argues about explicitly, but a team that does not need cross-institution trust does not need the complexity either.

The third case is a project with a data residency requirement. The primary database is hosted by Passport XYZ, the Ceramic data goes to a test network for development and to the network otherwise, and the attestations are on about a dozen public chains. A project that must keep its identity data inside one jurisdiction has to design around all of that, and the answer is likely to be a different architecture rather than a configuration change.

The fourth is a project that cannot run a monorepo of this shape. The local stack needs the app, the iam, ceramic and the scorer API, and the build order across eight workspaces is fixed. That is a lot of moving parts for a team that wants to evaluate whether the credential model fits their domain.

One licensing note to check before you build on it. The project metadata records the licence as a custom one that GitHub cannot classify, and there is a LICENSE file at the root of the repository. For a project that handles identity data, the exact terms matter more than usual, so read that file rather than assuming a standard OSS licence, and note that the package names in the ecosystem still carry the Gitcoin namespace.

## Conclusion

Passport fits a team building a credential-based application that wants its own issuer and verifier stack rather than a hosted identity provider, and it fits a developer already working in the verifiable credentials and Ceramic ecosystems. It does not fit a team that wants a turnkey identity product. Before you build on it, note that the runnable data path depends on the separate Passport Scorer API, that the Postgres database is hosted by Passport XYZ, and that the project metadata does not state a licence, so the LICENSE file in the repository is the one to read.

## FAQ

### What is Passport?

It is an identity verification application where people grow personal collections of verifiable credentials about themselves and organisations assess their identities to coordinate rights and responsibilities. The model is explicitly neither centralised like national identity cards nor individualistic like most self-sovereign identity models, but social and intersectional.

### What data does Passport use?

Three sources. The primary one is a Postgres database hosted by Passport XYZ, reached through the Passport Scorer API. The second is the Ceramic network, which needs no local setup. The third is onchain attestations made across about a dozen different networks.

### How do I run Passport locally?

You need Node v20 LTS, Yarn and Git. Clone the repository, install lerna globally, run `yarn install`, copy `./app/.env-example.env` to `./app/.env` and `./iam/.env-example.env` to `./iam/.env`, then run `yarn start` to start the iam, app and ceramic services. The Passport Scorer API has to be running separately for the data path.

### What are the main packages in the Passport monorepo?

The `app` web app, the `iam` server that issues credentials and processes verifications, the `identity` helper that compiles Spruce DIDKit, the `database-client` with Ceramic network support, `schemas` for Ceramic schemas and model definitions, `types` for shared definitions, and `embed` and `embed-popup`.

## Sources

- [Issues](https://github.com/passportxyz/passport/issues)
- [passportxyz/passport on GitHub](https://github.com/passportxyz/passport)
- [README](https://github.com/passportxyz/passport/blob/main/README.md)
- [Releases](https://github.com/passportxyz/passport/releases)

---

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