Skip to main content
The Orgo API accepts five authentication methods. The one you should use depends on who is calling and from where.
MethodWho uses itHeader
Api-TokenServers, scripts, CRON jobs you controlApi-Token: <token>
Bearer JWTA user who logged in with email + passwordAuthorization: Bearer <jwt>
OAuth 2.0A third-party app acting on behalf of an Orgo userStandard OAuth flow
OTPA user logging in via emailed one-time codeReturns a JWT, then Authorization: Bearer <jwt>
X-Contact-HashAn emailed contact opening an event linkX-Contact-Hash: <hash>
For most integrations the answer is Api-Token. The other four exist for specific user-facing flows.

​
Api-Token (server-to-server)

Generate a token at Settings → Developers → API Access. Send it as a raw header — there is no Bearer prefix and no encoding: 
curl https://your-org.orgo.space/api/v1/users \
  -H "Api-Token: 7f3c8b4e2a..."
Tokens carry one of two access levels:
  • Read/write — full access to whatever the owning user can do.
  • Read-only — any POST, PATCH, PUT, or DELETE is rejected with 403 Forbidden. Useful for analytics integrations.
Tokens inherit the permissions of the user that created them. If the user loses a role, the token loses the same access. Revoke a token by deleting it in the same UI — it stops working immediately.
Tokens grant durable access. Never commit them, log them, or send them to a client browser. Rotate periodically and prefer one token per integration so you can revoke individually.

​
JWT (interactive login)

For sessions started by a user typing email + password, exchange those credentials for a JWT: 
curl -X POST https://your-org.orgo.space/api/v1/login-check \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"<password>"}'
Response: 
{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "f3c7a..."
}
Send the JWT on every subsequent call: 
curl https://your-org.orgo.space/api/v1/me \
  -H "Authorization: Bearer eyJ0eXAi..."
JWTs are valid for approximately 11 days. After expiry, exchange the refresh token at POST /api/v1/token/refresh for a new pair. JWTs are scoped to the tenant the login was made against — calling a different tenant’s host with the same JWT will fail with 401.

​
OAuth 2.0 (third-party apps)

When you want users to “Log in with Orgo” from a third-party site, register an OAuth app at Settings → Developers → OAuth Applications and use the Authorization Code flow: 
1. Redirect user to:
   https://app.orgo.space/oauth/authorize
     ?client_id=YOUR_CLIENT_ID
     &redirect_uri=YOUR_CALLBACK
     &response_type=code
     &scope=profile+email
     &state=<csrf_token>

2. After approval, Orgo redirects to:
   YOUR_CALLBACK?code=<auth_code>&state=<csrf_token>

3. Exchange the code server-side:
   POST https://app.orgo.space/oauth/token
     grant_type=authorization_code
     code=<auth_code>
     client_id=YOUR_CLIENT_ID
     client_secret=YOUR_CLIENT_SECRET
     redirect_uri=YOUR_CALLBACK

4. Use the access token:
   GET https://app.orgo.space/oauth/userinfo
     Authorization: Bearer <access_token>
Available scopes: profile, email, groups, roles. Request only what you need — fewer scopes means a simpler consent screen for the user. Full setup walkthrough: OAuth Server.
Single-page apps cannot safely store the client secret. Use PKCE (add code_challenge and code_challenge_method=S256 to the authorize call) and skip the secret on the token exchange, or do the exchange server-side.

​
OTP (one-time password)

For users who do not have a password — or who prefer a magic-link flow — Orgo can send a 6-digit code by email. Two steps: 
# 1. Request the code
curl -X POST https://your-org.orgo.space/api/v1/request-login-otp \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com"}'

# 2. Verify the code (returns a JWT exactly like /login-check)
curl -X POST https://your-org.orgo.space/api/v1/verify-login-otp \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","otp":"483921"}'
OTP requests are rate-limited per email — typically 20 requests per 60 seconds — to prevent abuse. From there, the returned JWT is used exactly like the password-login JWT. OTP is also the auth method used by the event-app surface (members logging in from inside an event landing page) and for password resets.

​
X-Contact-Hash (anonymous contacts)

When Orgo emails a Contact (someone without a user account) an event invitation or a form link, the email contains a magic URL with a hash. That hash is also the auth header: 
curl https://your-org.orgo.space/api/v1/event_attends/12345 \
  -H "X-Contact-Hash: 9a8f7e6d5c..."
This authenticates the contact for that specific event and that specific contact identity — they cannot use the hash to access other contacts’ data. Most server-to-server integrations will not use this; it is here for completeness.

​
Picking the right method

Api-Token. Read-only if you only need to fetch data; read/write if you need to create or update.
JWT. Call POST /api/v1/login-check with the user’s credentials, store the returned JWT, and send it on every subsequent call.
OAuth 2.0. Register an OAuth application and follow the Authorization Code flow.
OTP. Two-step: request-login-otp then verify-login-otp. Returns a JWT.

​
Common authentication errors

StatusWhat it meansFix
401 UnauthorizedHeader missing, malformed, or invalid tokenRe-send the header; if the token is right, it may have been revoked or expired
403 ForbiddenAuthenticated, but lacks permission OR token is read-only and you sent a writeCheck Api-Token access level; check the user’s role for this resource
404 Not FoundResource exists but in a different tenantConfirm you are calling the correct subdomain — see Tenancy
  • Tenancy — getting the tenant context right is half of getting auth right
  • Errors — full error envelope reference
  • OAuth Server — admin-side setup for OAuth applications