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.
The account does not have to be a paying one. A free Fjord Account signs in to Fjord Commons, the shared instance, so you can use the app against a real Forgejo without provisioning anything.
Personal access token
Instances you provision on the Fjord platform sign in with your Fjord Account. Connecting directly needs no Fjord Account and no plan; a Fjord Account is optional there too, adding push notifications, notification actions, background Live Activity updates, multiple accounts, and switching between instances.
Sign in with its hostname and a Forgejo personal access token to point Fjord at any Forgejo 7.0 or later instance reachable over HTTPS, the same as the fj CLI. Create a token in Forgejo under your
profile, Settings, Applications, and give it the scopes Fjord uses. The
token stays on the device, and a direct session holds one server at a time.
Actions needs Forgejo 15+, and viewing run logs, cancelling a run, and
downloading artifacts need Forgejo 16+.
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 (agent)