Bring your own AI agent

Overview

Agent access lets an admin “use agents to do their work” without Diligio running (or paying for) a second AI. Your agent calls a small, fixed tool set: it searches your knowledge base, reads projects and questions, writes answers it composed, moves questions through review, and (at the highest level) exports a finished project. Every call is authenticated, permission-checked, and written to the audit log.

• Two transports, one tool set. Connect over MCP (Claude Desktop, the Agent SDK, and other MCP clients) or over a plain REST API. Both use the same bearer token and expose identical tools.
• Off by default. Nothing is reachable until a workspace admin enables it for your workspace and the individual user opts in.
• Never more than the human. A token can never exceed the permissions of the person who created it, re-checked live on every request.

How it works

A token always acts as a specific personin your workspace. When a request arrives, Diligio hashes the token, looks up the live token row, confirms the workspace switch and the user's opt-in are both on, reads that user's currentrole, and then runs the requested tool through a database session bound to that user. The database enforces exactly the rows the human can see; the tool's own role rules apply on top. The agent supplies the answer text; Diligio only embeds the search query (cheap) and stores what the agent produces. No Diligio answer-generation happens on an agent call.

Turn agent access on

Two independent switches must both be on. This is by design: the workspace owner controls the capability, and each user controls their own tokens.

1. Per workspace

Agent access is off by default for every workspace. A workspace admin turns it on under AI agent access in their profile, and can turn it off again at any time as an instant kill switch: every token in the workspace stops working immediately.

2. Per user (self-serve)

Once the workspace switch is on, every user sees an AI agent access card in their profile (Account Settings). It defaults to off. A user turns it on and mints their own tokens there. Turning their switch back off revokes all of that user's tokens at once.

Access levels & the RBAC ceiling

When a user mints a token they pick its level. The effective permission is always min(level, the user's live role) — the level can only ever narrow what the user can already do, never widen it.

• Live resolution. The user's role is read fresh on every request. Demote or offboard them and their tokens narrow or stop working on the very next call.
• Library-only users are pinned. A library_only account is forced to read-only no matter what level the token stored.
• Finalising is still admin-only. A “full” contributor agent can move a question to SME review but cannot finalise to Final, exactly like a human contributor. A full admin agent can.

Mint a token

In your profile's AI agent access card, create a token and choose its level. Diligio shows the full secret once— copy it then. We store only a SHA-256 hash, so we can never show it again; if it is lost, revoke it and mint a new one. Tokens look like this:

dgo_agent_<43 url-safe characters>

# example (do not use)
dgo_agent_K7m2xQ9...

Treat a token like a password. Anyone holding it can act as you, up to your token's level. Put it in a secret manager or your agent's credential store, never in source control.

Connect over MCP

Diligio exposes a Model Context Protocol server at https://www.diligio.co/api/mcp (Streamable HTTP, JSON-RPC 2.0). Point any MCP client at it with your token as a bearer header. For Claude Desktop, add a remote MCP server:

{
  "mcpServers": {
    "diligio": {
      "url": "https://www.diligio.co/api/mcp",
      "headers": {
        "Authorization": "Bearer dgo_agent_..."
      }
    }
  }
}

On connect, the client calls initialize and tools/list; Diligio returns only the tools your token's level grants. Your agent then calls them with tools/call. The same works from the Claude Agent SDK or any MCP-capable client — see the MCP section of the API reference for the raw JSON-RPC.

Connect over REST

If your agent is not MCP-based, the same tools are available as plain HTTPS. Start by confirming the token works:

BASE=https://www.diligio.co
TOKEN=dgo_agent_...

# Who am I, and what can this token do?
curl -s $BASE/api/agent/v1/me -H "Authorization: Bearer $TOKEN"

# List the tools this token's level grants (with input schemas)
curl -s $BASE/api/agent/v1/tools -H "Authorization: Bearer $TOKEN"

# Call a tool
curl -s -X POST $BASE/api/agent/v1/tools/kb_search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"data retention policy"}'

A worked example: answer a questionnaire

A “full” agent answering open questions in a project typically runs this loop. Notice the agent does its own writing — kb_search is grounding, and the agent must not invent facts beyond it.

BASE=https://www.diligio.co; TOKEN=dgo_agent_...

# a small helper so we don't repeat the headers each call
dgo() { curl -s -X POST "$BASE/api/agent/v1/tools/$1" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "$2"; }

# 1. Find the project
dgo list_projects '{}'

# 2. Pull the questions still being drafted
dgo list_questions '{"project_id":"<id>","status":"Drafting"}'

# 3. For each question, retrieve grounding...
dgo kb_search '{"query":"<the question text>","limit":5}'

# 4. ...your agent composes the answer from those hits, then writes it
dgo write_answer '{"question_id":"<id>","answer":"<text your agent wrote>"}'

# 5. Hand it to a human for review
dgo set_question_status '{"question_id":"<id>","new_status":"SME Review"}'

Answers written by an agent are flagged as agent-authored and enter the normal human review workflow — they are never silently published.

What an agent can do

The full tool set, and the level each tool needs. Read-only tokens see only the first row.

Each tool's exact input schema, an example call and its response are in the API reference.

Diligio Compliance

If your workspace runs Diligio Compliance and the user holds a GRC role, a much larger tool set appears: the full compliance system of record as an API. Your agent can work the frameworks (ISO 27001, SOC 2, GDPR, HIPAA, PCI DSS and more, cross-mapped), manage the risk, asset, policy, people, device, vendor and training registers, run or push continuous-monitoring checks, attach hash-anchored evidence, draft questionnaire answers, and drive audits end to end. Call /api/agent/v1/tools (or MCP tools/list) with your token and the complete, schema-documented set is returned; there is no hidden surface.

The intended loop is agent-native and cheap to run:

• grc_next_actions returns the whole prioritised worklist in one read: failing checks, overdue treatment, gaps without a plan, thin evidence, due reviews. Every item names the tool to call next.
• grc_evidence_recipe gives the per-control recipe: what proof the control needs, how fresh it must be, and the zero-custody route. One control per call, 200 reads per token per day.
• grc_propose_many stages up to 200 control statuses in one call, each citing its evidence, for a human to certify as a diff.
• grc_record_check_runs is push-mode monitoring: your runner executes checks on your own infrastructure with credentials that never reach Diligio, and pushes the verdicts. They land stamped self-attested, with provenance your auditor can read.
• grc_list_skills lists named skill playbooks (evidence review, remediation planning, re-attestation, zero-custody operations and more) your agent can adopt as task templates.

Prefer not to run an agent at all? The built-in Diligio agentdoes the same loop on Diligio’s models: a compliance admin clicks Run on the Compliance home, the agent fills cross-mapped frameworks, proposes evidence-backed statuses and drafts remediation, and everything still waits for a human to certify. Both routes are included; see the Compliance agent quickstart for copy-paste setup, including the full zero-custody push protocol.

Security & audit

• Hashed tokens. Only a SHA-256 hash is stored; the plaintext is shown once at creation.
• Trusted facts come from the token row only. Workspace, user and level are read from the database, never from the request body or headers.
• The database is the ceiling. The agent acts through a session bound to the human, so row-level security enforces the human's exact access. Capability checks and the existing role rules narrow from there.
• Everything is audited. Every agent action is written to the audit log with an “agent” actor type, the token id, and the self-reported agent label.

Revoke & kill switches

• A single token: the user revokes it from their profile; it stops on the next call.
• All of a user's tokens: the user turns their AI agent access switch off.
• The whole workspace: a workspace admin turns the workspace switch off.
• Implicitly: demoting or offboarding the user narrows or kills their tokens automatically, because the role is resolved live.

Troubleshooting

The complete status / code table and the MCP error behaviour are in the API reference. Still stuck? Email support@diligio.co.