Signing in
Fjord connects to a forge in one of two ways. You pick one when you sign in, and the app stores the host and credential securely on device.
Fjord Account
A Fjord Account is the sign-in for the hosted platform, and the recommended path for instances hosted on Fjord.
Choosing it opens the Fjord sign-in page in a secure in-app browser, where you authenticate to the Fjord platform with your email and password. Two-factor authentication is optional: you are prompted for a TOTP code only if you have enabled 2FA on your account. Fjord completes a standard OIDC authorization-code sign-in with PKCE and captures the result back in the app, without you leaving it. PKCE makes the app a public client with no shipped secret, so only the device that started the sign-in can complete it.
A Fjord Account authenticates against the Fjord platform’s own identity, not the Forgejo instance directly: it is the platform credential that grants access to the instance Fjord provisions for you.
Personal access token
Pointing the app at a self-hosted Forgejo instance that Fjord does not host for
you (a custom server) requires a Pro account. Instances you provision on the
Fjord platform sign in with your Fjord Account. This is a
mobile-app requirement; the fj CLI connects to
any Forgejo host with a personal access token at no extra cost.
With a Pro account you can point Fjord at any Forgejo instance: sign in with its hostname and a Forgejo personal access token. Create one in Forgejo under your profile, Settings, Applications, and give it the scopes Fjord uses.
Token scopes
Fjord’s current features need these scopes:
| Scope | Used for |
|---|---|
read:user, write:user | Your profile, starring, watching, following |
read:repository, write:repository | Browsing repos and code, and repo-level actions |
read:issue, write:issue | Issues and pull requests, comments, reactions, labels, merging |
read:notification, write:notification | The inbox, and marking notifications read |
A read-only token signs in fine but cannot perform Fjord’s write actions
(commenting, reactions, labels, pinning, merging pull requests, requesting
reviews, starring, watching, following, and marking notifications read). Grant
the write: scopes above if you want those.
Where credentials live
Fjord stores the host and your credential in the device Keychain, never in plain files. The current apps connect to a single host at a time. Signing out clears the stored credential.
If a session expires, Fjord asks you to sign in again rather than rotating a refresh token in the background.
- Stephen Way