Fargone is a full OAuth 2.0 provider. Third-party apps can authenticate users with their Fargone account.

Endpoints

Endpoint	Method	Purpose
/oauth/authorize	GET	Authorization code + PKCE
/oauth/token	POST	Token exchange
/oauth/userinfo	GET	User profile

Scopes

Scope	Access
read:user	Read user profile (default)
write:user	Modify user account
read:apps	List and read apps
write:apps	Create, deploy, and manage apps

Authorization code flow

1. Redirect the user to:

/oauth/authorize?client_id=fg_xxx&redirect_uri=https://your.app/callback&response_type=code&scope=read:user&state=random&code_challenge=abc&code_challenge_method=S256

2. The user sees a consent screen and approves.
3. Your redirect_uri receives a code query parameter.
4. Exchange the code for tokens:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=the_code&redirect_uri=https://your.app/callback&client_id=fg_xxx&client_secret=secret&code_verifier=the_verifier

5. Response:

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:user"
}

Device flow

For CLI or input-constrained devices:

1. Request a device code:

POST /api/oauth/device
Content-Type: application/json

{ "client_id": "fg_xxx", "scope": "read:user" }

2. Show the user_code and verification_uri to the user.
3. The user enters the code at /oauth/device in their browser.
4. Poll /oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code until the token is issued.

Get user info

GET /oauth/userinfo
Authorization: Bearer <access_token>

Returns: id, name (handle), preferred_username, email, avatar, role, status, scopes.

Refresh tokens

Access tokens expire after 1 hour. Refresh tokens do not expire.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=the_refresh_token&client_id=fg_xxx&client_secret=secret

Register a client

Go to Settings > OAuth Apps in the web UI, or use the API:

POST /api/oauth/clients
Content-Type: application/json

{
  "name": "My App",
  "description": "Does cool things",
  "redirectUris": ["https://my.app/callback"]
}

Client IDs are prefixed with fg_. Client secrets are shown only once at creation.

PKCE

PKCE is recommended for all clients. Both S256 and plain challenge methods are supported. If no code_challenge is provided, PKCE is skipped.