# Telagus - agent authentication

This document tells an AI agent how to obtain credentials for the Telagus CRM
API and the Telagus MCP server. It is the human- and agent-readable companion to
the machine-readable metadata linked at the bottom.

- **Site:** https://telagus.com
- **API base:** https://api.telagus.com/api/
- **MCP server:** https://api.telagus.com/mcp/telagus (Streamable HTTP)
- **Authorization server (issuer):** https://api.telagus.com

## What agents can do

Telagus is a multi-tenant CRM. An authenticated agent acts **on behalf of a
Telagus user**, and every request is scoped in code to that user's account. There
is no anonymous or tenant-wide access: an agent can only ever see and change the
data its user can see and change.

Available through the MCP server: leads and contacts, projects and tasks, quotes
and estimates, invoices, contracts, campaigns, SMS/MMS, phone numbers, forms,
users, attendance and leave. Query tools are read-only `SELECT`s validated
against the live schema before they run.

## Identity model

| | |
| --- | --- |
| Identity type | `delegated` - the agent acts for a signed-in Telagus user |
| Credential type | `oauth2_access_token` (Bearer) |
| Grant | `authorization_code` with PKCE (`S256`), plus `refresh_token` |
| Scope | `mcp:use` |
| Client registration | Dynamic Client Registration (RFC 7591), open |

## Registering and authenticating

1. **Discover.** Fetch the authorization server metadata:

   ```http
   GET https://api.telagus.com/.well-known/oauth-authorization-server
   ```

   Unauthenticated calls to the MCP server also point you there, per RFC 9728:

   ```http
   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: Bearer realm="mcp",
     resource_metadata="https://api.telagus.com/.well-known/oauth-protected-resource/mcp/telagus"
   ```

2. **Register.** POST your client metadata to the registration endpoint. No
   pre-shared secret or manual approval is required.

   ```http
   POST https://api.telagus.com/oauth/register
   Content-Type: application/json

   {
     "client_name": "Your agent",
     "redirect_uris": ["https://your-agent.example/callback"],
     "grant_types": ["authorization_code", "refresh_token"],
     "response_types": ["code"],
     "token_endpoint_auth_method": "none"
   }
   ```

3. **Authorize.** Send the user to the authorization endpoint with PKCE. The user
   signs in to Telagus and consents; the agent inherits only that user's access.

   ```
   https://api.telagus.com/oauth/authorize
     ?response_type=code
     &client_id=YOUR_CLIENT_ID
     &redirect_uri=https://your-agent.example/callback
     &scope=mcp:use
     &code_challenge=YOUR_CHALLENGE
     &code_challenge_method=S256
     &state=YOUR_STATE
   ```

4. **Exchange.** Trade the code for tokens at
   `https://api.telagus.com/oauth/token`, then call the MCP server with
   `Authorization: Bearer <access_token>`. Refresh with the `refresh_token`
   grant; do not re-prompt the user while a refresh token is valid.

## Revoking access

A Telagus user can revoke an agent's access at any time from their Telagus
account settings, which invalidates that agent's tokens. There is no public
token revocation endpoint; revocation is user-initiated in the product.

## Rules for agents

- Act only within the authenticated user's account and permissions.
- Prefer the read-only `execute_*_select_query` tools for questions; use the
  write tools only when the user has asked for a change.
- Outbound messaging tools (SMS, MMS, email campaigns) contact real people.
  Confirm with the user before sending.
- Respect the content signals in https://telagus.com/robots.txt: this site's
  content may be indexed and used to ground cited answers, but not used to train
  or fine-tune models.

## Machine-readable metadata

| Document | URL |
| --- | --- |
| Authorization server metadata (RFC 8414) | https://api.telagus.com/.well-known/oauth-authorization-server |
| Protected resource metadata (RFC 9728) | https://api.telagus.com/.well-known/oauth-protected-resource/mcp/telagus |
| Protected resource metadata (site root) | https://telagus.com/.well-known/oauth-protected-resource |
| API catalog (RFC 9727) | https://telagus.com/.well-known/api-catalog |
| MCP server card | https://telagus.com/.well-known/mcp/server-card.json |
| Capability manifest (ARD) | https://telagus.com/.well-known/ai-catalog.json |
| Agent skills index | https://telagus.com/.well-known/agent-skills/index.json |
| OpenAPI description | https://api.telagus.com/docs |

Questions: https://telagus.com/contact-us