Authentication

Pubky apps request scoped access to a user’s Homeserver through grant authentication. A key manager such as Pubky Ring lets the user approve the request without giving the app their identity key.

From approval to a session

An application asks for the permissions its features need, such as reading and writing files in its own storage path. It presents an authorization link or QR code. The user reviews the request in their authenticator, which approves access and delivers an encrypted grant through an HTTP Relay. The SDK turns that approval into a session the app can use for authenticated requests.

The app’s session is distinct from the identity key. Its permissions limit what it can access on the Homeserver, and grants can be revoked. Reading someone else’s public data does not require their approval; writing data or accessing authenticated storage does. The Security Model explains these boundaries.

Review requested scopes before approving an app. Root grants carry account-level privileges and should be reserved for trusted account-management tools.

Signing out

Signing out an active grant-backed session through the SDK revokes its grant. Revocation invalidates every session issued from that grant and prevents saved credentials for it from restoring access. Separate grants, including those issued to the same app, are unaffected.

Removing saved browser session data only forgets it locally; it does not revoke the grant on the Homeserver. If the session token is no longer valid, SDK sign-out can report success without revoking the grant.

Implement the flow

Use the SDK guides to implement this flow:

• JavaScript grant authentication.
• Rust QR authentication.
• Browser session persistence example.

For raw endpoints, see the Homeserver API references. For key custody and Homeserver trust, read the Security Model.