Integrate "Log in with Orgo" (OAuth)

This walkthrough adds “Log in with Orgo” to a third-party application. It uses the OAuth 2.0 authorization code flow with PKCE.

Every URL here is on the tenant’s own host — acme.orgo.space in these examples, or the organization’s custom domain. The bare app.orgo.space domain resolves no tenant and returns 404. See Tenancy.

Who is this for: SaaS apps your members use that should not require a second login (member-only forums, member-only deals platforms, internal tools, partner services).

When to use OAuth vs Api-Token

Api-Token — your server acts as itself; the data is yours. Use for backend integrations, dashboards, batch jobs.
OAuth — your server acts on behalf of an Orgo user; you only see what that user can see. Use when each end-user logs into your app as themselves.

If you’re building a single integration that consumes “all members of Civic Collective”, that’s an Api-Token. If you’re building a forum where each Orgo member logs in individually, that’s OAuth.

Prerequisites

A callback URL on your app served over HTTPS (localhost is allowed for development).
For a confidential client: an admin in the Orgo tenant who can create the app.

Step 0 — Read the discovery document

Don’t hardcode endpoints. Every tenant publishes its own metadata, and issuer reflects the host you fetch it from:

curl https://acme.orgo.space/.well-known/oauth-authorization-server

Use authorization_endpoint, token_endpoint and userinfo_endpoint from the response. Fetch this once per tenant you integrate with — never reuse one tenant’s document for another.

Step 1 — Register your client

Public client (self-service)
Confidential client (admin)

Best for SPAs, mobile apps, and anything that cannot keep a secret. No admin involvement and no authentication needed, but limited to 10 registrations per hour per IP:

curl -X POST https://acme.orgo.space/api/v1/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": ["https://your-app.example.com/oauth/callback"],
    "client_name": "Civic Forum"
  }'

Returns 201 with a client_id. No secret is issued — PKCE is your only client authentication. Optional metadata: client_uri, logo_uri, policy_uri, tos_uri.

In the Orgo admin UI: Developer → Apps → Create Application.

Field	What to enter
Name	What users see during authorization — “Civic Forum”
Redirect URIs	Exact callback URLs (one per line) — exact match required
Scopes	What the app requests on the consent screen
Act on behalf of members	Off makes the app read-only — see step 7

Orgo returns a Client ID and a Client Secret (one-time, store server-side only).

Step 2 — Redirect the user to authorize

When a user clicks “Log in with Orgo” in your app, redirect them to:

https://acme.orgo.space/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.example.com/oauth/callback
  &scope=profile+email+groups
  &state=<csrf_token>
  &code_challenge=<base64url(sha256(verifier))>
  &code_challenge_method=S256

Parameter	Purpose
`response_type`	Always `code`
`client_id`	The Client ID from Step 1
`redirect_uri`	Must match a registered URI exactly (including trailing slash)
`scope`	Space-separated list — see scopes
`state`	Random string you generate per-request; check on callback to prevent CSRF
`code_challenge`	`BASE64URL(SHA256(code_verifier))`
`code_challenge_method`	Always `S256`

PKCE is mandatory for every client, confidential ones included — this is stricter than baseline OAuth 2.0 and matches OAuth 2.1. The server rejects violations with invalid_request:

code_challenge_method must be S256; plain is not supported.
Both code_challenge and code_verifier must match [A-Za-z0-9-._~]{43,128}.

If the member isn’t signed in, Orgo handles login and returns them to the consent screen automatically — including via Google, Apple or Microsoft. You don’t handle that.

Step 3 — Receive the callback

Orgo sends the user back to your redirect_uri with two parameters:

https://your-app.example.com/oauth/callback?code=<auth_code>&state=<csrf_token>

Verify state matches the one you stored, then move on.

Step 4 — Exchange the code for an access token

Form-encoded body, not JSON. A confidential client does this server-side — the Client Secret must never reach the browser.

Public client
Confidential client

PKCE only. Sending a client_secret here is an error (invalid_client):

curl -X POST https://acme.orgo.space/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$AUTH_CODE" \
  -d "client_id=$CLIENT_ID" \
  -d "code_verifier=$PKCE_VERIFIER" \
  -d "redirect_uri=https://your-app.example.com/oauth/callback"

Send the code_verifier and authenticate. Pick exactly one authentication method — client_secret_basic here, or client_secret_post via a client_secret field:

curl -X POST https://acme.orgo.space/api/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$AUTH_CODE" \
  -d "client_id=$CLIENT_ID" \
  -d "code_verifier=$PKCE_VERIFIER" \
  -d "redirect_uri=https://your-app.example.com/oauth/callback"

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "f3c7a...",
  "scope": "profile email groups"
}

The code is single use. Redeeming it twice fails with invalid_grant — and a replay by an authenticated client revokes the tokens that code already produced. Never retry a code after a successful exchange. (A retry after a failed client authentication is safe: the code stays redeemable so you can fix credentials and try again.)

Step 5 — Use the access token

The access token works as a normal Bearer JWT.

curl https://acme.orgo.space/api/v1/oauth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response:

{
  "sub": "42",
  "name": "James Patterson",
  "email": "james.patterson@example.com",
  "picture": "https://cdn.orgo.space/users/42/avatar.jpg",
  "groups": ["main-group", "boston-local"],
  "roles": ["ROLE_USER", "ROLE_MEMBER"]
}

sub is the user’s stable Orgo ID — use this as the primary key in your app’s users table. Email can change; sub cannot. You can also use the same access token to call other API endpoints scoped to the user’s permissions:

curl https://acme.orgo.space/api/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Step 6 — Refresh expired tokens

Access tokens last 1 hour (expires_in in the original response). Refresh tokens last 30 days. Use the refresh token to get a new pair without sending the user back through the consent screen:

curl -X POST https://acme.orgo.space/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=$CLIENT_ID"

Confidential clients authenticate here too, exactly as in step 4.

Refresh tokens rotate. Each refresh returns a new refresh_token and invalidates the one you just sent. Persist the new value every time — an app that keeps replaying its original refresh token will work once and then start failing with invalid_grant.

Do not call refresh on every API request — only when a request returns 401.

Step 7 — Know what your token cannot do

Two limits catch most integrations, and neither is adjustable per request. An app acts as a member, never as an administrator. The token is capped to member level (ROLE_USER) no matter who authorized it. If a tenant administrator connects your app, it still cannot perform administrator actions. Read-only apps are gated by HTTP method. If the app is registered read-only it may use GET, HEAD and OPTIONS only. Anything else returns 403:

This application has read-only access and may not act on your behalf.

The gate is by method, not intent — an endpoint that performs a read via POST is still blocked. If you need those, register the app with acting enabled.

Available scopes

Scope	What the member is asked to approve
`profile`	Name, profile picture, display name
`email`	Email address
`groups`	Group + local-center memberships
`roles`	User roles (`ROLE_USER`, `ROLE_MEMBER`, `ROLE_ADMIN`, etc.)

Scopes describe what an application requests and what the member approves when they authorize it. What the resulting token can actually reach is bounded by the member-level cap and the application’s read-only / act-on-behalf setting in step 7.

Request only what you need — fewer scopes makes the consent screen shorter and clearer.

Common gotchas

`invalid_redirect_uri` on the authorize call

The redirect_uri parameter must match a registered URI exactly. Watch for: trailing slashes, http vs https, port numbers (8080 vs 443), and URL encoding of query strings. Register every variant you use (dev, staging, prod) at creation.

The user authorized but I never received the code

Check that your callback handler is reachable from Orgo’s servers (not localhost-only behind a firewall) and serves HTTPS (except for localhost URIs which can use HTTP). Check browser network tab — Orgo issues a 302 to the callback; if your handler 500s, it shows there.

Token exchange returns `invalid_client`

Wrong client_id, wrong client_secret, or a confidential client omitting its secret entirely (that one returns 401 with WWW-Authenticate: Basic realm="orgo-oauth"). A public client sending a client_secret also fails — it has none, and PKCE is its only authentication.Note that sending client_secret and code_verifier together is correct for a confidential client: PKCE applies to every client. What is not allowed is sending credentials by more than one method at once — Basic header and form field — which returns invalid_request.

Token exchange returns `429 rate_limit_exceeded`

Repeated failed client authentications for the same client_id are throttled: after 10 failures in 5 minutes you get 429 with a Retry-After header instead of 401. This means your credentials are wrong, not that you are calling too often — a request with the correct secret is never throttled, however many failures came before it. Fix the secret rather than backing off.

The user's groups don't match what I see in the Orgo UI

The groups scope returns slug-style group names, not display names. To resolve to a full Group resource, call GET /api/v1/units?slug=boston-local separately.

My app is a SPA — can I skip the backend entirely?

Use PKCE without a Client Secret. Generate a verifier (random 43-128 chars), hash it with SHA-256, base64url-encode the hash, send the hash as code_challenge on authorize, then send the verifier as code_verifier on token exchange. The Client Secret stays unused.

A token that looks valid is being rejected

Access tokens are RS256 JWTs, but they are revocable server-side and revocation takes effect on the next request. A token whose signature verifies and whose exp is still in the future can still be rejected.Do not treat a local expiry check as proof a token works — handle 401 at any point in a token’s lifetime and fall back to refresh, then to re-authorization. Verify signatures against jwks_uri from the discovery document.

What to do next

Authentication — comparison of OAuth vs Api-Token vs JWT vs OTP, and the full discovery reference
Migrating from legacy SSO — if you already use the *-sso handshake
OAuth Server — admin-side documentation on managing OAuth applications
Tenancy — how OAuth tokens carry tenant scope

​When to use OAuth vs Api-Token

​Prerequisites

​Step 0 — Read the discovery document

​Step 1 — Register your client

​Step 2 — Redirect the user to authorize

​Step 3 — Receive the callback

​Step 4 — Exchange the code for an access token

​Step 5 — Use the access token

​Step 6 — Refresh expired tokens

​Step 7 — Know what your token cannot do

​Available scopes

​Common gotchas

​What to do next

When to use OAuth vs Api-Token

Prerequisites

Step 0 — Read the discovery document

Step 1 — Register your client

Step 2 — Redirect the user to authorize

Step 3 — Receive the callback

Step 4 — Exchange the code for an access token

Step 5 — Use the access token

Step 6 — Refresh expired tokens

Step 7 — Know what your token cannot do

Available scopes

Common gotchas

What to do next