> ## Documentation Index
> Fetch the complete documentation index at: https://monid.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up OAuth

> Let your users sign in with Monid and act on their own workspace via OAuth 2.0.

Use OAuth 2.0 to let your users authorize your service to call the Monid API on their behalf. This is the right choice when your users manage their own Monid account and wallet.

## 1. Request OAuth Credentials

Email [support@monid.ai](mailto:support@monid.ai) to obtain:

* **Client ID**
* **Client Secret**
* **Whitelisted redirect URIs** (only required if you host your own callback)

If you don't have a callback URL, you can use Monid's hosted callback to display the authorization code for the user to copy and paste:

```text theme={null}
https://app.monid.ai/oauth/code/callback
```

## 2. OAuth Configuration

| Parameter              | Value                                                            |
| ---------------------- | ---------------------------------------------------------------- |
| **Issuer**             | `https://clerk.app.dev.monid.ai`                                 |
| **Resource**           | `https://api.monid.ai`                                           |
| **Redirect URI**       | Your own callback, or `https://app.monid.ai/oauth/code/callback` |
| **Discovery document** | `https://clerk.app.monid.ai/.well-known/openid-configuration`    |

Monid follows standard OAuth 2.0 / OpenID Connect. Point your OAuth client library at the discovery document above and it will auto-configure the authorization, token, userinfo, and introspection endpoints.

### Scopes

Request any subset of the following:

| Scope            | Purpose                                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `openid`         | Required for OIDC. Enables ID tokens.                                                                            |
| `profile`        | User's name and profile info.                                                                                    |
| `email`          | User's email address.                                                                                            |
| `offline_access` | Return a refresh token so you can act while the user is offline.                                                 |
| `use:org:read`   | Read the user's organizations and workspaces (needed to call [`GET /v1/auth/workspaces`](/api/auth/workspaces)). |

## 3. Authorization Flow

Monid uses the standard OAuth 2.0 **authorization code** flow (with PKCE recommended for public clients). Any OIDC-compliant client library will work — see [oauth.net](https://oauth.net/2/) or your library's docs for reference.

The flow at a glance:

<Steps>
  <Step title="Redirect the user to /oauth/authorize">
    Include `client_id`, `redirect_uri`, `scope`, `resource=https://api.monid.ai`, and a `state` value.
  </Step>

  <Step title="Exchange the returned code at /oauth/token">
    You'll get back an `access_token` and (if `offline_access` was requested) a `refresh_token`.
  </Step>

  <Step title="Use the access token">
    Send `Authorization: Bearer <access_token>` on every Monid API call.
  </Step>
</Steps>

<Note>
  For the exact request/response shape of each endpoint, use the [OIDC discovery document](https://api.monid.ai/.well-known/openid-configuration) — it's the canonical source and always up to date.
</Note>

## 4. Select a Workspace

A Monid user can belong to multiple workspaces. **Every request to the Monid API must include an `x-workspace-id` header** so Monid knows which workspace to operate against.

List the workspaces the user has access to — see [`GET /v1/auth/workspaces`](/api/auth/workspaces):

```bash theme={null}
curl https://api.monid.ai/v1/auth/workspaces \
  -H "Authorization: Bearer <access-token>"
```

Pick a workspace and include its ID on every subsequent call:

```bash theme={null}
curl -X POST https://api.monid.ai/v1/discover \
  -H "Authorization: Bearer <access-token>" \
  -H "x-workspace-id: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{"query":"twitter posts"}'
```

## 5. Call the API

Once you have an access token and a workspace ID, use the standard Monid API. See the [API Reference](/api/overview) for all available endpoints.

<Note>
  Access tokens from OAuth act like scoped API keys. Never expose them to end‑user browsers or mobile clients — keep them on your server.
</Note>