Arcnode developers

Login with Arcnode

Let people sign in to your app with their Arcnode account. Backboard is a standard OAuth 2.0 and OpenID Connect provider using the Authorization Code flow with PKCE.

Endpoints

Base URL: https://backboard.arcnode.dev. Discovery is machine readable, so most OIDC libraries only need the issuer URL.

DiscoveryGET/.well-known/openid-configuration

JWKSGET/.well-known/jwks.json

AuthorizationGET/oauth/authorize

TokenPOST/oauth/token

UserInfoGET/oauth/userinfo

Scopes

openidRequired for OpenID Connect. Returns an id_token and a stable sub.

profileGrants access to the account display name.

emailGrants access to the account email address.

1. Create a PKCE verifier and challenge

PKCE is mandatory and only the S256 method is accepted. Generate a random code_verifier, then derive the challenge.

// code_verifier: 43-128 chars from [A-Za-z0-9-._~]
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)))

// code_challenge = base64url(SHA-256(verifier))
const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
const challenge = base64url(new Uint8Array(digest))

2. Redirect the user to authorize

Send the user to the authorization endpoint. The redirect_uri must exactly match one you registered. Keep the state and verifier in the user session.

GET https://backboard.arcnode.dev/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://app.example.com/callback
  &scope=openid%20profile%20email
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

Arcnode shows a consent screen. On approval the user is returned to your redirect_uri with ?code=...&state=.... Verify state matches before continuing.

3. Exchange the code for tokens

Confidential clients authenticate with their client_secret (HTTP Basic or in the body). Public clients (for example SPAs) omit the secret and rely on PKCE. Always send the code_verifier.

POST https://backboard.arcnode.dev/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)   // confidential only

grant_type=authorization_code
&code=THE_CODE
&redirect_uri=https://app.example.com/callback
&code_verifier=THE_VERIFIER
&client_id=YOUR_CLIENT_ID

200 OK
{
  "access_token": "eyJhbGciOiJSUzI1Ni...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJSUzI1Ni...",
  "refresh_token": "..."
}

Tokens are RS256 JWTs. Verify them against the keys at /.well-known/jwks.json with issuer https://backboard.arcnode.dev and audience equal to your client_id.

4. Read the profile

Call userinfo with the access token to read the claims your scopes allow.

GET https://backboard.arcnode.dev/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

200 OK
{ "sub": "user_id", "email": "you@example.com", "email_verified": true, "name": "Your Name" }

5. Refresh tokens

Access tokens live for one hour. Use the refresh token to get a new one. Refresh tokens rotate: each use returns a new refresh token and invalidates the old one.

POST https://backboard.arcnode.dev/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=THE_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

Getting a client_id

Client registration is handled by Arcnode owners and admins. If you run Arcnode, open the OAuth clients page to register an app. Otherwise contact the Arcnode team with your app name and redirect URIs. You receive a client_id and a client_secret shown only once.

Security notes

PKCE with S256 is required for every client.
redirect_uri is matched exactly, so register every callback URL you use.
Authorization codes are single use and expire after 60 seconds.

Secured by Arcnode identity