Profile and environments
Where each setting lives
| Field | Purpose | Production rule |
|---|---|---|
| App name | Primary picker identity users see. | Derived from the public app profile; edit it there. |
| Client ID | Stable app identifier and selection-token audience. | Use an HTTPS URL you control. Local dev can use the ATProto http://localhost/ shortcut. |
| Logo URL | Visual identity in the picker. | Derived from the public app profile; use a reachable HTTPS image. |
| Homepage | Human-readable app identity. | Derived from the public app profile; use HTTPS and align it with the client ID domain. |
| Allowed return URIs | Callbacks allowed to receive selection_token. | Exact-match production URLs. Loopback IP callbacks are local development only. |
| Preferred account host (optional) | Pins a host first in the Create Account chooser and labels it as recommended by the app. | Must be joinable and either managed by the app DID or connected by a verified app-host relationship. This site re-verifies it when the picker opens. |
Client ID versus return URI
For local ATProto OAuth development, http://localhost/ is a special virtual client ID. Your local callback is still a return URI, usually http://127.0.0.1:<port>/... or http://[::1]:<port>/....
Registration review states
| State | Picker label | Behavior |
|---|---|---|
| development | Development app | Local-only app. Good for loopback testing, not production trust. |
| unverified | Unverified app | Self-registered app. Picker shows clear warning copy. |
| trusted | Trusted | Reviewed app identity and return URI allow-list. |
| blocked | Unavailable | Picker cannot continue. |
Allowed return URI rules
- Production return URIs must be exact matches.
- Fragments are stripped and are never used as delivery locations.
- A registered origin is not a wildcard for every callback path.
- Keep staging, preview, and production callbacks explicit.
- Remove loopback URLs before requesting trusted review.