# OhAuthCat Passport

Passport is for **IT administrators** at your customers. When their company uses several apps that run on OhAuthCat, an admin can create one Passport and link each app to it, so they do not have to prove the same domain or hunt for each vendor's setup page again. It is opt-in and never on the sign-in path: if Passport is unavailable, sign-ins are not affected.

## Create a Passport

From any vendor's setup portal, the admin chooses to create or link a Passport:

1. They enter an email address on one of their company's verified domains and receive a code. The answer is the same whether or not a Passport already exists for that address.
2. The portal hands the browser over to the Passport app at `https://passport.ohauthcat.com/enrol` with a one-time token. The token is single use, valid for 10 minutes and bound to that enrolment and vendor; reloading the page within that time works. An unknown, expired or used token answers [`passport_handoff_invalid`](/errors/passport_handoff_invalid/), and the admin starts again from the vendor's portal.
3. On the Passport app they register a passkey (or use the one they already have).
4. The vendor is linked, with the consents they choose. `passport.linked` is written to the vendor's audit log and to the Passport trail.

Passport passkeys use the Passport host (`passport.ohauthcat.com`) as their relying party ID, separate from your end users' passkeys.

## What a vendor can see

Nothing crosses from one vendor to another without the admin's consent for that vendor. The consents are:

| Consent        | Allows                                                                                                     |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| `domain_proof` | Reusing a domain the admin proved at another vendor. The DNS record is checked again each time it is used. |
| `guidance`     | Setup guidance based on how the admin's identity provider is set up elsewhere.                             |
| `read`         | Showing this vendor's connection status in the Passport, and starting certificate rotation from it.        |

## The Passport view

Signed in with a passkey, the admin sees every linked vendor, changes or withdraws consent (effective immediately), unlinks a vendor, and starts a certificate rotation, which opens that vendor's setup portal through a single-use link valid for 5 minutes.

A rotation is allowed only when the Passport was linked through a setup-portal link with the `sso` or `edit_connection` [intent](/hosted-portal/intents/); linking again through such a link adds the right. Links made through other intents, or before intents were recorded, answer [`passport_rotation_not_permitted`](/errors/passport_rotation_not_permitted/) (403). Send the admin a new portal link with the `sso` intent if they need to rotate. The Passport keeps its own audit trail; each vendor's audit log records `passport.linked`, `passport.unlinked`, `passport.grant_changed`, `passport.domain_proof_used`, `passport.domain_proof_lent` and `passport.rotation_started`.

Sessions last 8 hours at most and end after 30 minutes idle. With [data residency](/data-residency/), a Passport shows only the vendors in the same region.

## For developers

You do not need to build anything: Passport is offered from the hosted setup portal, not from your app. When the IT admin confirms enrolment in the portal, the portal hands them over to the Passport app, which finishes the enrolment there.

`GET /v1/passport/links` (scope `organizations:read`) lists which of your organizations are linked to a Passport, with the link status, the linked and unlinked times and the consents granted. It never shows who holds the Passport.

`DELETE /v1/passport/links/{link}` (scope `organizations:write`) unlinks a Passport from one of your organizations at once. All of its consents are revoked, so it can no longer lend domain proof, read setup status or start a rotation. The answer is the ended link with `status: unlinked`; the holder sees the unlink in their Passport activity, and your audit log records `passport.unlinked`. A link of another environment, or one already ended, answers 404.

```http
DELETE /v1/passport/links/pptl_01J9Z3K5V7W8X9Y0Z1A2B3C4D5 HTTP/1.1
Host: api.ohauthcat.com
Authorization: Bearer <secret key>
```

Errors: [`passport_code_invalid`](/errors/passport_code_invalid/), [`passport_consent_required`](/errors/passport_consent_required/), [`passport_domain_proof_failed`](/errors/passport_domain_proof_failed/) and [`passport_rotation_not_permitted`](/errors/passport_rotation_not_permitted/).
