Loading documentation…

Loading…

Docs / Getting Started / Quickstart

Quickstart

Run your first scan

From an empty account to a confirmed finding in under five minutes. This guide uses the REST API — if you'd rather use the dashboard, see the UI walkthrough instead.

1. Get your API key

Every request to the Orithos API is authenticated with a bearer token scoped to your organisation. Generate one from Settings → API Keys in the dashboard, or via the CLI:

bash

$ orithos auth login
# Opens a browser window for OAuth — the key is stored in
# ~/.orithos/credentials, never printed to stdout

API keys inherit the RBAC scopes of the user who generated them. A key generated by an Auditor-role user cannot trigger scans, regardless of what the request body contains.

Prefer the API? POST /v1/api-keys creates a key programmatically — response includes the plaintext once; we only store a bcrypt hash.

2. Create an agent

An agent is the unit Orithos scans — your system prompt, tool manifest, RAG sources, and guardrail declarations, described once and reused across every scan.

POST/v1/agents

bash

curl https://api.orithos.com/v1/agents \
  -H "Authorization: Bearer $ORITHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Assistant",
    "endpoint_url": "https://api.openai.com/v1/chat/completions",
    "system_prompt": "You are a helpful support assistant...",
    "tools_config": [
      {
        "name": "order_lookup",
        "description": "Look up an order by ID",
        "parameters": {"order_id": {"type": "string", "required": true}}
      }
    ]
  }'

The response includes an id (e.g. agt_8f2a1c) — save it, you'll need it for every subsequent call. See Agents for the full schema (provider presets, headers, memory_config, guardrails).

3. Connect an endpoint

Orithos sends probes to your agent's actual running deployment. A connection is a URL and an auth method — no SDK installed on your side, no code changes to your agent. You can set endpoint_url directly on the agent (step 2), or manage a dedicated connection:

Field	Type	Description
endpoint_url required	string	Your agent's chat completion endpoint
auth_type optional	enum	`bearer` · `api_key` · `none`
format optional	enum	`openai_compatible` · `anthropic`

Credentials are Fernet-encrypted at rest. Health checks run every 6 hours — or hit POST /v1/agents/:id/verify for an immediate check.

4. Trigger the scan

POST/v1/scans

bash

curl https://api.orithos.com/v1/scans \
  -H "Authorization: Bearer $ORITHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_8f2a1c",
    "connection_id": "cxn_44e01b",
    "intensity": "deep"
  }'

# Response — 202 Accepted
{
  "scan_id": "scn_a3f9c21",
  "status": "running"
}

intensity is quick (1 probe/category) or deep (full catalog + permutations). Add connection_id when the same agent has multiple endpoints (staging vs production).

5. Poll for results

GET/v1/scans/:scan_id

A typical deep scan completes in under 5 minutes. Poll every 5–10 seconds, or subscribe to the WebSocket stream (see Running a scan) to avoid polling entirely.

json

{
  "scan_id": "scn_a3f9c21",
  "status": "complete",
  "risk_score": 6.4,
  "findings": {
    "critical": 0, "high": 1, "medium": 2, "low": 0
  },
  "findings_url": "https://api.orithos.com/v1/findings?scan_id=scn_a3f9c21"
}

Fetch full evidence at GET /v1/findings?scan_id=scn_a3f9c21 or export HTML / PDF / SARIF from the dashboard.

Findings responses include the exact probe text and agent response for every violation. See Understanding Findings for the full schema and how severity is determined.

Prefer a terminal? The Orithos CLI wraps every endpoint on this page — plus orithos skill scan for vetting skills and plugins offline.

← PREVIOUSIntroduction NEXT →Agents

Key concepts

Keep these in mind as you move beyond the quickstart.

Agent

An LLM endpoint registered with Orithos. Orithos probes your agent by sending requests to this endpoint and analyzing responses.

Probe

A single security test case targeting a specific vulnerability class. Orithos ships 100+ probes covering prompt injection, tool misuse, data leakage, and privilege escalation.

Scan

An execution of a probe set against an agent. Scans run asynchronously via a Redis-backed worker queue. Each scan produces findings with severity grades.

Finding

A detected vulnerability with a severity rating and CVSS 4.0 score. Each finding includes an attack path, evidence, and remediation guidance.

Attack Path

The sequence of tool calls or inputs that leads to a vulnerability. Attack paths explain exactly how an exploit works against your agent.

Compliance Mapping

Findings are automatically mapped to 10 frameworks: OWASP LLM, OWASP Agentic, DORA TLPT, CWE, MITRE ATLAS, NIST AI RMF, SOC 2, ISO 27001, HIPAA, and NIST 800-53.

Explore further

Agents

Scans

Monitor, rerun, and compare scans.

Findings

Severity, CVSS, and evidence.

Compliance

Framework mappings and audit reports.

MCP Registry

Tools and policies.

Security

Encryption and audit logging.

Findings Feed

Push findings to your CNAPP or SIEM.

Loading documentation…

Docs / Getting Started / Quickstart

Quickstart

Run your first scan

From an empty account to a confirmed finding in under five minutes. This guide uses the REST API — if you'd rather use the dashboard, see the UI walkthrough instead.

1. Get your API key

Every request to the Orithos API is authenticated with a bearer token scoped to your organisation. Generate one from Settings → API Keys in the dashboard, or via the CLI:

bash

$ orithos auth login
# Opens a browser window for OAuth — the key is stored in
# ~/.orithos/credentials, never printed to stdout

API keys inherit the RBAC scopes of the user who generated them. A key generated by an Auditor-role user cannot trigger scans, regardless of what the request body contains.

Prefer the API? POST /v1/api-keys creates a key programmatically — response includes the plaintext once; we only store a bcrypt hash.

2. Create an agent

An agent is the unit Orithos scans — your system prompt, tool manifest, RAG sources, and guardrail declarations, described once and reused across every scan.

POST/v1/agents

bash

curl https://api.orithos.com/v1/agents \
  -H "Authorization: Bearer $ORITHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Assistant",
    "endpoint_url": "https://api.openai.com/v1/chat/completions",
    "system_prompt": "You are a helpful support assistant...",
    "tools_config": [
      {
        "name": "order_lookup",
        "description": "Look up an order by ID",
        "parameters": {"order_id": {"type": "string", "required": true}}
      }
    ]
  }'

The response includes an id (e.g. agt_8f2a1c) — save it, you'll need it for every subsequent call. See Agents for the full schema (provider presets, headers, memory_config, guardrails).

3. Connect an endpoint

Field	Type	Description
endpoint_url required	string	Your agent's chat completion endpoint
auth_type optional	enum	`bearer` · `api_key` · `none`
format optional	enum	`openai_compatible` · `anthropic`

Credentials are Fernet-encrypted at rest. Health checks run every 6 hours — or hit POST /v1/agents/:id/verify for an immediate check.

4. Trigger the scan

POST/v1/scans

bash

curl https://api.orithos.com/v1/scans \
  -H "Authorization: Bearer $ORITHOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_8f2a1c",
    "connection_id": "cxn_44e01b",
    "intensity": "deep"
  }'

# Response — 202 Accepted
{
  "scan_id": "scn_a3f9c21",
  "status": "running"
}

intensity is quick (1 probe/category) or deep (full catalog + permutations). Add connection_id when the same agent has multiple endpoints (staging vs production).

5. Poll for results

GET/v1/scans/:scan_id

A typical deep scan completes in under 5 minutes. Poll every 5–10 seconds, or subscribe to the WebSocket stream (see Running a scan) to avoid polling entirely.

json

{
  "scan_id": "scn_a3f9c21",
  "status": "complete",
  "risk_score": 6.4,
  "findings": {
    "critical": 0, "high": 1, "medium": 2, "low": 0
  },
  "findings_url": "https://api.orithos.com/v1/findings?scan_id=scn_a3f9c21"
}

Fetch full evidence at GET /v1/findings?scan_id=scn_a3f9c21 or export HTML / PDF / SARIF from the dashboard.

Findings responses include the exact probe text and agent response for every violation. See Understanding Findings for the full schema and how severity is determined.

Prefer a terminal? The Orithos CLI wraps every endpoint on this page — plus orithos skill scan for vetting skills and plugins offline.

← PREVIOUSIntroduction NEXT →Agents

Key concepts

Keep these in mind as you move beyond the quickstart.

Agent

An LLM endpoint registered with Orithos. Orithos probes your agent by sending requests to this endpoint and analyzing responses.

Probe

A single security test case targeting a specific vulnerability class. Orithos ships 100+ probes covering prompt injection, tool misuse, data leakage, and privilege escalation.

Scan

An execution of a probe set against an agent. Scans run asynchronously via a Redis-backed worker queue. Each scan produces findings with severity grades.

Finding

A detected vulnerability with a severity rating and CVSS 4.0 score. Each finding includes an attack path, evidence, and remediation guidance.

Attack Path

The sequence of tool calls or inputs that leads to a vulnerability. Attack paths explain exactly how an exploit works against your agent.

Compliance Mapping

Findings are automatically mapped to 10 frameworks: OWASP LLM, OWASP Agentic, DORA TLPT, CWE, MITRE ATLAS, NIST AI RMF, SOC 2, ISO 27001, HIPAA, and NIST 800-53.

Explore further

Agents

Scans

Monitor, rerun, and compare scans.

Findings

Severity, CVSS, and evidence.

Compliance

Framework mappings and audit reports.

MCP Registry

Tools and policies.

Security

Encryption and audit logging.

Findings Feed

Push findings to your CNAPP or SIEM.