# SiberMate Developer Platform

SiberMate Developer Platform provides documentation and machine-readable contracts for integrating with SiberMate security awareness data and workflows.

## What SiberMate Covers

SiberMate supports security awareness operations across:

- Learners and learner lifecycle.
- Admin users (platform administrators), which are distinct from learners: admins run SiberMate, learners take the training.
- Organization plan and free-trial status.
- Learner groups and group managers.
- Training courses and gap analysis.
- Phishing simulations and simulation metrics.
- Policies, policy templates, acknowledgements, reminders, and policy lifecycle workflows.
- Breach exposure visibility.
- Tenant reports and security awareness progress.

## Primary URLs

- Developer docs: https://docs.sibermate.com/
- MCP guide: https://docs.sibermate.com/mcp
- MCP for Claude: https://docs.sibermate.com/mcp/claude
- MCP for Codex: https://docs.sibermate.com/mcp/codex
- MCP for Cursor: https://docs.sibermate.com/mcp/cursor
- MCP for VS Code: https://docs.sibermate.com/mcp/vscode
- MCP for Windsurf: https://docs.sibermate.com/mcp/windsurf
- MCP for Zed: https://docs.sibermate.com/mcp/zed
- Static API reference: https://docs.sibermate.com/api-reference
- Markdown API reference: https://docs.sibermate.com/api-reference.md
- Sitemap: https://docs.sibermate.com/sitemap.xml
- Robots: https://docs.sibermate.com/robots.txt
- OpenAPI JSON: https://api.sibermate.com/v1/openapi.json
- REST API base URL: https://api.sibermate.com/v1
- Remote MCP server URL: https://mcp.sibermate.com/mcp
- Guided MCP setup URL: https://mcp.sibermate.com/setup
- npm stdio bridge: https://www.npmjs.com/package/@sibermatedev/mcp

## REST API Guidance

The REST API uses bearer authentication:

```http
Authorization: Bearer <SIBERMATE_API_KEY>
```

The public API is tenant-scoped by the authenticated API key. Standard keys should not provide or infer tenant/company IDs outside the documented request schema. The one documented exception is the optional `companyId` parameter for MSP and Distributor keys, described below.

Useful REST areas include:

- `/companies`
- `/company`
- `/company/features`
- `/learners`
- `/groups`
- `/courses`
- `/reports/*`
- `/policies`
- `/policy-templates`
- `/simulations`
- `/breaches/accounts`
- `/breaches/services`

Use the OpenAPI JSON contract for exact request and response schemas. Use
`https://docs.sibermate.com/api-reference.md` when a crawler or AI agent needs a
plain Markdown endpoint reference without rendering the interactive API UI.

### MSP and Distributor Cross-Tenant Reads

MSP and Distributor API keys can read across the child tenants they manage:

- `GET /v1/companies` returns the managed child tenant companies. This endpoint is restricted to MSP and Distributor keys; other keys receive 403.
- Tenant-scoped read endpoints accept an optional `companyId` query parameter to scope the read to one child tenant, using an ID from `GET /v1/companies`. Omit `companyId` to read your own organization.

This cross-tenant capability is read-only. Standard tenant keys stay scoped to their own organization, and passing a foreign `companyId` with a non-MSP key returns 403.

## MCP Guidance

Use this URL as the remote MCP server endpoint:

```text
https://mcp.sibermate.com/mcp
```

Compatible clients discover OAuth metadata from that endpoint and open the browser authorization flow automatically. During setup, the user approves a SiberMate tenant API key and receives refreshable MCP bearer tokens. OAuth authorization code flows require S256 PKCE.

Do not use this URL as the MCP server endpoint:

```text
https://mcp.sibermate.com/setup
```

`/setup` is only a guided browser fallback for clients that cannot launch OAuth automatically.

If a client does not support remote MCP OAuth but does support custom headers, use a dedicated tenant API key as:

```http
Authorization: Bearer <SIBERMATE_API_KEY>
```

If a client only supports local or stdio MCP servers, run a local bridge or proxy that connects to `https://mcp.sibermate.com/mcp` and injects the authorization header from a local environment variable.

Bearer fallback mode remains tenant-scoped, but OAuth token refresh is handled only when the client completes the remote OAuth flow.

Recommended local stdio bridge command:

```bash
npx -y @sibermatedev/mcp
```

Use `@sibermatedev/mcp` version `0.1.1` or newer. The bridge sends bearer auth only to `https://mcp.sibermate.com/mcp` by default. Custom `SIBERMATE_MCP_URL` values are rejected unless `SIBERMATE_MCP_ALLOW_CUSTOM_URL=1` is explicitly set for a trusted development endpoint.

Static client-specific setup pages are available without JavaScript:

- Claude: https://docs.sibermate.com/mcp/claude
- Codex: https://docs.sibermate.com/mcp/codex
- Cursor: https://docs.sibermate.com/mcp/cursor
- VS Code: https://docs.sibermate.com/mcp/vscode
- Windsurf: https://docs.sibermate.com/mcp/windsurf
- Zed: https://docs.sibermate.com/mcp/zed

Example remote MCP client configuration (recommended):

```json
{
  "mcpServers": {
    "sibermate": {
      "type": "http",
      "url": "https://mcp.sibermate.com/mcp",
      "headers": {
        "Authorization": "Bearer <SIBERMATE_API_KEY>"
      }
    }
  }
}
```

Clients that only support local stdio MCP servers can instead run the
`npx -y @sibermatedev/mcp` bridge shown above.

## MCP Tooling Model

SiberMate MCP exposes business-action tools, not a generic GraphQL passthrough. The first MCP launch is read-only: MCP tokens and direct bearer fallback may retrieve tenant context, but are not authorized to create, update, upload, remove, deactivate, unenroll, or delete tenant data through MCP.

Tools are grouped by risk:

- Read tools: inspect tenant, admin users, learners, groups, courses, reports, policies, policy templates, simulations, and breach exposure. MSP and Distributor keys can also list managed child companies (`sibermate_list_companies`) and scope read tools to a child tenant with a `companyId` argument.
- Write tools: create or update learners, groups, assignments, reminders, and policy workflows.
- Reminder/send tools: course reminders, gap analysis reminders, and policy reminders.
- Destructive tools: delete, remove, unenroll, deactivate, discard, and bulk cleanup actions.

Some REST capabilities are deliberately not tools. Creating, updating, deleting, or re-inviting an admin user is REST-only: a new SiberMate admin receives full platform administrator access and SiberMate has no read-only admin tier, so that decision must not be reachable from an AI client. MCP can only list admins. Permanent deletion of learners, policies, and policy templates is likewise REST-and-console only. When a user asks for any of these through an AI client, point them at the REST API or the SiberMate console instead of attempting a tool call.

AI clients should call `sibermate_get_tool_help` before planning routines, write actions, reminders, or destructive changes. This tool returns workflow guidance, tool clusters, automation playbooks, and safety rules. Treat write, reminder, and destructive clusters as documented capabilities for future or explicitly approved deployments unless the active MCP token grants the required scope.

## Automation Use Cases

Good read-only MCP automation prompts include:

- "Act as my weekly security awareness analyst. Check training, policy, phishing, and breach signals, identify learners who need attention, and draft recommended follow-up."
- "Create an onboarding plan for these new learners using existing groups, courses, and policies. Return the plan for human execution."
- "Find policy acknowledgement gaps and draft a reminder workflow for approval outside MCP."
- "Review breach exposure, map affected accounts to learner context, and recommend follow-up training or manager escalation."

## Safety Requirements For AI Agents

- Use a dedicated SiberMate API key for automation.
- Never expose API keys, bearer tokens, or tenant data in logs, public repos, screenshots, or shared prompts.
- Never invent learner, group, course, policy, simulation, or template IDs. Read them from SiberMate first.
- Do not ask for or pass company IDs with standard tenant keys; tenant scope comes from authentication. The optional `companyId` parameter applies only to MSP and Distributor keys for read-only cross-tenant access, as documented in the API reference.
- Do not attempt write, reminder, or destructive tool calls unless the active deployment grants the required server-side scope.
- Preview mutation plans before any external execution outside read-only MCP.
- Ask for explicit confirmation before destructive actions unless a host automation policy has already approved the action.
- For policy category fields, use values returned by existing policies or templates; omit the category if unsure.
- Review AI-generated answers and action logs against source records before using them for compliance, HR, or security decisions.

## Crawler Notes

The docs site is crawlable and public. Tenant data and MCP tool calls require authorization. Crawlers should use the docs, sitemap, OpenAPI JSON, and this LLM context file for public documentation, not authenticated tenant endpoints.