OAuth Server

Orgo can act as an OAuth 2.0 provider. This means your members can use their Orgo credentials to log in to your website, internal tools, or partner applications — “Login with Orgo” — without creating separate accounts.

When to use this

You want to…	OAuth Server?
Let members log in to your website with their Orgo account	Yes
Authenticate users in a custom mobile app	Yes
Provide SSO for internal tools (wiki, project manager)	Yes
Give partner services access to member data (with consent)	Yes
Let external people log in to Orgo using Google/Microsoft	No — that’s SSO Authentication (inbound), not OAuth Server (outbound)

How it works

1. User clicks "Login with Orgo" on your app
   ↓
2. User is redirected to Orgo's login page
   ↓
3. User authenticates and approves access
   ↓
4. Orgo redirects back with an authorization code
   ↓
5. Your app exchanges the code for an access token
   ↓
6. Your app uses the token to get user info

This is the standard OAuth 2.0 Authorization Code flow.

Setting up an OAuth application

Developer → Apps → Create Application

OAuth Apps management page showing configured applications

Field	What to enter
Name	What users see during authorization — “My Organization Website”
Description	What the app does (for your reference)
Redirect URIs	Where Orgo sends users after authorization — must match exactly
Scopes	What the app requests on the consent screen
Act on behalf of members	Leave on for an app that creates or changes data. Turn off for a reporting or analytics integration — see below

After creating the app, you’ll receive a Client ID and Client Secret. Store the secret securely — it’s shown only once.

Apps you create here are confidential clients. Developers can also self-register public clients against your tenant without admin involvement; those get no secret and are limited to the same member-level access. See Authentication for that path.

Read-only or acting on behalf

Every app is either read-only or permitted to act on the member’s behalf. New apps can act by default. A read-only app may use GET, HEAD and OPTIONS only. Anything else is rejected with 403 and the message “This application has read-only access and may not act on your behalf.”

The limit is by HTTP method, not intent. A few endpoints perform a read via POST — a read-only app cannot call those either. If a partner reports being blocked on something that only reads data, this is usually why.

Whichever setting applies is shown to the member on the consent screen before they approve.

What an app can never do

A token issued to an app is capped to member level, no matter who authorizes it. If one of your administrators connects the app, it still cannot perform administrator actions. This is deliberate and not configurable. An app acts as a member, never as an administrator — so connecting a third-party app cannot escalate that party to admin access over your tenant.

OAuth endpoints

Clients should read these from the discovery document at /.well-known/oauth-authorization-server rather than hardcoding them.

Endpoint	Purpose
`/authorize`	Where you send users to log in and approve
`/api/v1/oauth/token`	Where your server exchanges the code for a token
`/api/v1/oauth/userinfo`	Where your server retrieves the authenticated user’s data
`/api/v1/oauth/register`	Self-service registration for public clients
`/api/v1/oauth/jwks.json`	Public keys for verifying token signatures

All of these live on your tenant’s own host — acme.orgo.space, or your custom domain.

Orgo includes a built-in OAuth documentation page that developers can reference when building integrations:

Built-in OAuth developer documentation page

Implementation

Step 1: Redirect to authorization

Send users to Orgo’s authorization endpoint. PKCE is required — including for confidential apps like the ones you create here:

GET /authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=profile email&
  state=CSRF_TOKEN&
  code_challenge=BASE64URL(SHA256(verifier))&
  code_challenge_method=S256

Step 2: Exchange code for token

After the user authorizes, Orgo redirects to your URI with a code. Exchange it server-side:

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

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=ORIGINAL_VERIFIER&
redirect_uri=YOUR_REDIRECT_URI

Step 3: Get user info

Use the access token to retrieve the user’s profile:

GET /api/v1/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Response:

{
  "sub": "user-uuid",
  "name": "John Doe",
  "email": "john@example.com",
  "picture": "https://...",
  "groups": ["main-group", "local-center"],
  "roles": ["ROLE_USER"]
}

Available scopes

Scope	What it grants access to
`profile`	Name, profile picture
`email`	Email address
`groups`	Group memberships
`roles`	User roles and permissions

Request only the scopes your app needs — fewer scopes means less data exposure and a simpler consent screen for users.

Common scenarios

I get 'invalid redirect URI' errors

The redirect URI in your authorization request must exactly match one of the URIs registered in the OAuth app settings. Watch for trailing slashes, http vs https, and port numbers.

Access tokens are expiring

Access tokens last one hour. Use the refresh token to get a new one without sending the member back through consent. Refresh tokens last 30 days and rotate — each refresh returns a new one and invalidates the previous, so the app must store the new value every time.

Can I use this with a single-page app (SPA)?

Yes. A SPA should self-register as a public client rather than using an app created here — it gets no Client Secret, and PKCE alone authenticates it. PKCE is mandatory for every client either way, so a confidential app sends both its secret and the code_verifier.

How do I map Orgo roles to permissions in my app?

Use the roles scope to get the user’s Orgo roles. In your app, map these roles to your permission system — e.g., Orgo ADMIN_TENANT → your app’s admin role.

Never expose the Client Secret in client-side code (JavaScript, mobile apps). The secret must stay on your server. All token exchanges should happen server-to-server.

Integrations — Connect third-party services to Orgo
Members — User data that OAuth provides access to

Home

Organization

Users & Profiles

Groups

Communication

Events

Payments & Fees

Governance

Resources

Support

Customization

Developers

OAuth Server

When to use this

How it works

Setting up an OAuth application

Read-only or acting on behalf

What an app can never do

OAuth endpoints

Implementation

Step 1: Redirect to authorization

Step 2: Exchange code for token

Step 3: Get user info

Available scopes

Common scenarios

​When to use this

​How it works

​Setting up an OAuth application

​Read-only or acting on behalf

​What an app can never do

​OAuth endpoints

​Implementation

​Step 1: Redirect to authorization

​Step 2: Exchange code for token

​Step 3: Get user info

​Available scopes

​Common scenarios

​Related

When to use this

How it works

Setting up an OAuth application

Read-only or acting on behalf

What an app can never do

OAuth endpoints

Implementation

Step 1: Redirect to authorization

Step 2: Exchange code for token

Step 3: Get user info

Available scopes

Common scenarios

Related