Integrate OLPN into an existing platform

OLPN is designed to be implemented by hosts, not just by individual users. A platform that implements the protocol gives every user a verifiable OLPN identity without asking them to manage JSON files or understand identifiers. This guide covers the common integration patterns.

Case study: publish.law

The publish.law platform is a personal attorney site host. Attorneys sign up, fill in their profile and credentials in a standard web form, and publish at their own domain. Under the hood, publish.law:

• Maintains a per-account record of profile, properties, and credentials in its database.
• Serves a computed /olpn.json for each account, reading from that record.
• Serves the corresponding /olpn-property.json at the same domain, naming the account's entity as owner.
• When an attorney pastes a credential ID in their admin, the platform verifies it against the issuer's olpn-credential.json and, if successful, stores the credential alongside the others.

The attorney never sees the JSON, the identifier format, or the fetch rules. They see a form that says "Add a credential". The protocol lives in the platform's implementation, not in the user's workflow.

The three integrations a host needs

1. Serve the entity document

For every account, serve /olpn.json at that account's domain. Include only verified credentials in the served document. Unverified user claims should be stored for the user's own reference but not published, because the resolver will fail on them and the user will get a confusing "why did my credential disappear from the public view" experience.

2. Serve the self-property document

Serve /olpn-property.json at the same domain, with the account's network_id in ownership[]. This completes the two-way back-link for the self-property and makes the account's own domain a verified property.

3. Verify claimed credentials at write time

When a user adds a credential to their account, fetch the issuer's credential document and check the back-link. Two outcomes:

• Back-link matches. Store the credential and include it in the published olpn.json. Show the user a "verified" indicator in the admin.
• Back-link missing or mismatched. Store the credential as a user claim, but don't include it in olpn.json. Show the user a diagnostic in the admin so they can ask the issuer to fix the back-link.

Re-verify periodically so revocations are picked up. A weekly or monthly re-check is sufficient.

Custom domains

Platforms that let users bring their own domain have to think about what happens to the network ID when the domain changes. Two approaches:

• Move the identity. When the custom domain is added, change the account's network ID from §:entity:{subdomain}.platform.com to §:entity:{custom-domain}. Notify issuers that the back-link target has changed (out-of-band; the protocol has no notify mechanism). This is the cleanest long-term state but requires user migration work.
• Serve at both. Publish olpn.json at both the subdomain and the custom domain, with both network IDs being valid. This is simpler but leaves two parallel identities that consumers have to reconcile.

publish.law took the first approach. Issuers are asked to update back-links when attorneys move to a custom domain. This has friction, but the identity model stays clean.

Edge caching

Entity and property documents benefit from aggressive caching. They change only when the user edits their profile. A typical caching policy:

Cache-Control: public, s-maxage=31536000, stale-while-revalidate=86400
Vary: Host

Purge at the edge when the user mutates their record. Without a purge mechanism, the cache will hold stale content for up to a year, which is disastrous for a credential that was just revoked.

Exporting an identity

A platform that takes OLPN seriously should give users an export button that emits a ZIP containing:

• olpn.json
• olpn-property.json
• A static HTML mirror of the user's public-facing pages, with embedded <script id="olpn-hub"> fallbacks.
• A README explaining how to deploy the ZIP to any static host and keep the same network ID.

This makes the identity portable away from the platform. Users who know they can leave with their data behave differently from users who feel locked in; the entire point of an open protocol is to make that exit path real.

What you don't need to do

• You don't need to run a resolver. Point users at olpn.org or any other resolver.
• You don't need to sign anything. The protocol doesn't use signatures.
• You don't need to enumerate. You don't publish a list of your accounts anywhere in the protocol. Each account's document is independent.
• You don't need to federate. You serve documents at domains. That's the federation.