OAuth for partner apps
A partner app, an automation tool or a custom app that works for a MonoChat user can call the custom-function API (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) with an OAuth access token instead of an API token. The user approves the app on a MonoChat page, chooses the tenants it may reach, and can revoke it at any time under Connected apps in their profile settings.
API tokens keep working on the same endpoint. OAuth is the option for an app that acts for other people: it never sees a password or an API token, and each user can cut it off on their own.
A call made with an access token runs as the user who approved the app, with that user's roles. It runs the tenant's custom methods only, and only in tenants where the user is an agent.
Get a client
Ask MonoChat for a client for your app. MonoChat registers it with:
- the app's name, which the approval page and Connected apps show;
- its redirect URIs, matched exactly:
httpsaddresses, orhttponlocalhost,127.0.0.1or[::1](any port); - the scopes it may ask for:
custom-functions:runfor this API.
You receive a client ID (it starts with monochat_rc_) and a client secret (it starts with monochat_cs_). The secret is shown once; MonoChat stores only its hash. Keep it on your server, never in a browser or a mobile app.
An app that cannot keep a secret, such as one running in the browser or on the user's computer, can instead use the URL of a client ID metadata document as its client ID, as MCP clients do. It then sends no secret.
Endpoints
The authorization server metadata at https://app.monochat.ai/.well-known/oauth-authorization-server lists every endpoint. On a white-label or self-hosted installation, use that installation's own address.
| Setting | Value |
|---|---|
| Authorization endpoint | https://app.monochat.ai/oauth/authorize |
| Token endpoint | https://app.monochat.ai/oauth/token |
| Revocation endpoint | https://app.monochat.ai/oauth/revoke |
| Resource | https://app.monochat.ai/api/custom-functions |
| Scope | custom-functions:run |
| Client authentication | HTTP Basic, or client_id and client_secret in the request body |
The resource's own metadata is at https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.
Connect a user
MonoChat uses the authorization code flow with PKCE (S256). The user needs two-step verification (by e-mail or an authenticator app) set up.
- Send the user to the authorization endpoint with
response_type=code, yourclient_id, aredirect_uriyou registered,scope=custom-functions:run,resource=https://app.monochat.ai/api/custom-functions, astateand acode_challengewithcode_challenge_method=S256. - The user signs in to MonoChat if needed. The approval page names your app and shows Run custom methods for you. The user may pick the Tenants the app can reach (all of theirs when none is picked), enters their 6-digit confirmation code and clicks Allow.
- MonoChat sends the user back to your
redirect_uriwithcode,stateandiss. If the user clicks Deny, it sendserror=access_deniedinstead. - Exchange the code at the token endpoint within 5 minutes:
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>
The answer holds an access_token (it starts with monochat_at_) valid for expires_in seconds (an hour), a refresh_token (it starts with monochat_rt_) and the granted scope.
Call the API
Send the access token as a bearer token:
curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
| Status | When |
|---|---|
401 | The token is unknown, expired or revoked, or it was issued for another resource, such as the MCP server. The WWW-Authenticate header points to the resource metadata. |
403 | The tenant is not one the user allowed for the app, the user has no access to the tenant, or the grant lacks custom-functions:run. |
429 | A limit is hit; wait for the seconds in Retry-After. Calls are counted per minute: 120 per grant and 1,200 per client, besides the tenant's own limit for this endpoint. |
Refresh and revoke
- Refresh: before the access token expires, call the token endpoint with
grant_type=refresh_tokenand therefresh_token. Each refresh returns a new refresh token; use the new one. A refresh token used again more than a minute after it was replaced ends the grant. - Expiry: the grant ends 90 days after its last refresh, when the user revokes it under Connected apps, or when the user changes or resets their password. The user then has to approve the app again.
- Revoke: to disconnect a user, post the access or refresh token to the revocation endpoint with your client authentication:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>
Connecting the same user to your app again replaces their earlier grant.