For Applications (OAuth)

Connect your application to Monid via OAuth 2.0 and call the authenticated Monid API on behalf of a Monid user. This is the right choice when you are building a platform or product that acts for your users' Monid accounts (rather than a single API key tied to one workspace).

Monid is an OAuth 2.0 resource server — it validates access tokens and serves the API. Clerk is the authorization server that runs the login/consent screen and issues tokens. Your application runs a standard 3-legged authorization code flow with PKCE.

1. Get Credentials

OAuth client credentials are issued by Monid, one per integrating platform — you do not self-register.

Email support@monid.ai to discuss your use case. We will provision an OAuth application for your platform and send you:

• a client_id
• a client_secret
• your registered redirect URI(s) (tell us the callback URL(s) your app uses)

Scopes granted: openid profile email offline_access.

Keep the client_secret confidential — never ship it in a browser or mobile client. Public clients (SPA / native / CLI) use PKCE without a secret; tell us if that is your case.

2. Discover the OAuth Endpoints

Your application can auto-discover the authorization server from the Monid API domain using the standard OAuth well-known documents:

# Protected resource metadata (RFC 9728)
curl https://api.monid.ai/.well-known/oauth-protected-resource

# Authorization server metadata (points at Clerk's authorize/token endpoints)
curl https://api.monid.ai/.well-known/oauth-authorization-server

The protected-resource document advertises:

• resource — https://api.monid.ai/v1
• authorization_servers — the authorization server (Clerk) origin
• scopes_supported — openid, profile, email, offline_access
• bearer_methods_supported — header

The authorization-server document provides authorization_endpoint and token_endpoint, which you use in the next step.

3. Authorize and Exchange for a Token

Run the authorization code flow with PKCE against the discovered endpoints.

# 1. Generate a PKCE verifier + challenge
VERIFIER=$(openssl rand -base64 60 | tr -d '\n=+/' | cut -c1-64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary \
  | openssl base64 | tr '+/' '-_' | tr -d '=\n')

# 2. Send the user to the authorization endpoint (from step 2 discovery).
#    Replace <AUTHORIZE_URL> with authorization_endpoint from discovery.
open "<AUTHORIZE_URL>?response_type=code\
&client_id=$CLIENT_ID\
&redirect_uri=$REDIRECT_URI\
&scope=openid%20profile%20email%20offline_access\
&code_challenge=$CHALLENGE\
&code_challenge_method=S256"

# 3. After the user authorizes, your redirect URI receives ?code=<AUTH_CODE>.
#    Exchange it at the token endpoint (from discovery) for tokens.
curl -X POST "<TOKEN_URL>" \
  -d grant_type=authorization_code \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d redirect_uri="$REDIRECT_URI" \
  -d code="<AUTH_CODE>" \
  -d code_verifier="$VERIFIER"

The token response includes an access_token (the OAuth bearer token you send to Monid) and, because offline_access is granted, a refresh_token.

Redirect URI

Your redirect_uri must be registered with your OAuth application (tell us the callback URL(s) when you request credentials). It must match exactly — scheme, host, port, and path.

If you don't yet have your own callback endpoint (for example while testing from a CLI), Monid hosts an authorization-code handoff page you can use as the redirect URI:

https://app.monid.ai/oauth/code/callback

After the user authorizes, this page displays the short-lived authorization code with a copy button (it never shows the access token). Copy the code and paste it into your client to complete the token exchange. Ask us to register this URI on your OAuth app if you'd like to use it.

4. Select a Workspace

OAuth tokens are scoped to a user, not a workspace. Before calling workspace-scoped endpoints, list the user's workspaces and pick one:

curl https://api.monid.ai/v1/auth/workspaces \
  -H "Authorization: Bearer <access_token>"

{
  "workspaces": [
    { "workspaceId": "org_123", "slug": "acme", "name": "Acme Inc" }
  ]
}

Pass the chosen workspace (id or slug) as the x-workspace-id header on every subsequent request. The user must be a member of that workspace.

5. Call the API

Send the access token as a Bearer token, plus x-workspace-id:

curl -X POST https://api.monid.ai/v1/run \
  -H "Authorization: Bearer <access_token>" \
  -H "x-workspace-id: acme" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "apify", "endpoint": "/apidojo/tweet-scraper", "input": { "searchTerms": ["AI"], "maxItems": 10 } }'

An OAuth token can call every authenticated /v1/* endpoint, exactly like an API key — see the API Reference.

Errors

Errors use the standard { "code", "message" } shape:

• 401 — missing or invalid access token.
• 403 — valid token, but no x-workspace-id (on a workspace-scoped endpoint), or the user is not a member of the named workspace. Call GET /v1/auth/workspaces to see valid workspaces.

OAuth vs API Keys

• Use OAuth when your application acts on behalf of your users' Monid accounts (a platform integration).
• Use an API key when you are calling Monid for a single workspace you control (scripts, backends, one workspace).