Connect a REST client

← Agents

Use REST when your own program, not an MCP client, works with Monomer. The program signs in as you through your browser, receives short-lived tokens for the REST API, and calls the same operations an MCP agent uses. Monomer has no screen that issues tokens or API keys, and you never copy a token from Monomer.

The program acts as you, with your roles, in the Workspaces you’re a member of. Its connection appears in Your settings → Agents with the label REST API.

What your program needs

Value	Address
Token audience (`resource`)	`https://api.monomer.cc/v2/workspaces`
REST base URL	`https://api.monomer.cc/v2`
Authorization server metadata	`https://api.monomer.cc/.well-known/oauth-authorization-server`
Protected resource metadata	`https://api.monomer.cc/.well-known/oauth-protected-resource/v2/workspaces`

The authorization server metadata lists the authorize, token, and revoke endpoints. Use the addresses it returns.

Identify your program

Monomer identifies OAuth clients by Client ID Metadata Documents (CIMD). Your client ID is an HTTPS URL that you control, on the default port, without a query or fragment. That URL returns application/json metadata for a public client:

{
  "client_id": "https://tools.example.com/monomer-client.json",
  "client_name": "Example Reporting Tool",
  "redirect_uris": ["http://127.0.0.1/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

client_id must equal the URL that serves the document, and client_name is the name people see when they approve the connection. Redirect URIs must be HTTPS or loopback HTTP. For a loopback URI such as http://127.0.0.1/callback, Monomer accepts the same host and path on any port, so a desktop program can listen on a free port. Monomer does not offer dynamic client registration and uses no client secret. Do not reuse another app’s client ID.

Create a random PKCE code verifier, its S256 code challenge, and a random state value.

Open this address in the user’s browser, with each value URL-encoded:

GET https://api.monomer.cc/oauth/authorize?response_type=code&client_id={client-id-url}&redirect_uri={redirect-uri}&resource=https://api.monomer.cc/v2/workspaces&scope=agent.workspace&code_challenge={challenge}&code_challenge_method=S256&state={state}

The user completes the Monomer sign-in flow and approves Connect {App} to Monomer.
Monomer redirects to your redirect URI with code, state, and iss. Continue only when state matches the value you sent and iss is https://api.monomer.cc.

Exchange the code within five minutes. Send a form body without an Authorization header:

POST https://api.monomer.cc/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={client-id-url}&redirect_uri={redirect-uri}&resource=https://api.monomer.cc/v2/workspaces&code={code}&code_verifier={verifier}

The response contains access_token, token_type (Bearer), expires_in, refresh_token, and scope (agent.workspace). A code works once.

Keep the connection working

An access token lasts 15 minutes. Before it expires, send grant_type=refresh_token with client_id, resource, and refresh_token to the same token endpoint.
Each refresh returns a new refresh token and invalidates the one you sent. If a used refresh token is sent again, Monomer revokes the whole connection, so keep only the newest token and refresh one request at a time.
The connection expires 30 days after approval. Refreshing does not extend it; sign in again to keep access.
Store tokens in the operating system’s secure storage. Do not put them in source code, logs, shared files, or chat.
To disconnect, send client_id and the token to https://api.monomer.cc/oauth/revoke as a form body, or revoke the connection in Your settings → Agents.

Call the API

Send every request with Authorization: Bearer {access-token} and Content-Type: application/json. First list the Workspaces you can access:

POST https://api.monomer.cc/v2/agent/list
Authorization: Bearer {access-token}
Content-Type: application/json

{"path":"workspaces"}

Then work in a chosen Workspace, for example listing its metrics:

POST https://api.monomer.cc/v2/workspaces/{workspaceId}/agent/list
Authorization: Bearer {access-token}
Content-Type: application/json

{"path":"workspace/metrics","limit":20}

The URL supplies the target, so omit workspaceId from the body. The Agent API reference lists every operation with its request body and response codes, and Direct your agent explains how to choose a target. A token for the MCP server is rejected by REST, and a REST token is rejected by the MCP server, because each has its own audience.

A 401 means the token is missing, expired, or revoked: refresh it or sign in again. A missing or inaccessible Workspace returns 404; a 403 means your role does not allow the operation. Errors describes the error body.

Connect a REST client

What your program needs

Identify your program

Sign in and get tokens

Keep the connection working

Call the API