How AI assistants drive security scans — ephemeral sessions, API-guided flows, CLI hints, and shareable results.
Brigs is designed to be driven by AI assistants. Every API response includes structured guidance for what to do next — agents never need to hardcode the flow.
There are two integration paths depending on whether the user has an account:
No signup required. Create a session, scan one repo, get shareable results. Session expires in 72 hours.
brigs_eph_Full API access with an API key. Unlimited scans, continuous monitoring, remediation, evidence generation.
brigs_sk_Five steps from zero to a shareable security posture score. The agent drives the entire flow — the only human step is clicking one OAuth link.
Agent calls the session creation endpoint. No authentication required. Returns a slug, token, and URLs for every subsequent step.
POST https://api.brigs.ai/ephemeral/sessions
Content-Type: application/json
{ "email": "[email protected]" } # optionalResponse (201):
{
"slug": "coral-fox-92",
"sessionToken": "brigs_eph_abc123...",
"connectUrl": "https://brigs.ai/connect/coral-fox-92",
"resultsUrl": "https://brigs.ai/scan-results/coral-fox-92",
"statusUrl": "https://api.brigs.ai/ephemeral/sessions/coral-fox-92/status",
"expiresAt": "2026-02-26T12:00:00.000Z",
"nextSteps": [
{ "step": 1, "action": "connect_vcs", "instruction": "Ask the user to open connectUrl..." },
{ "step": 2, "action": "poll_status", "instruction": "Poll statusUrl every 3-5 seconds..." },
{ "step": 3, "action": "add_repo", "instruction": "GET /integrations/github to find..." },
{ "step": 4, "action": "trigger_scan", "instruction": "POST /scans with { repoId }..." },
{ "step": 5, "action": "poll_results", "instruction": "Poll statusUrl until scan complete..." }
]
}The agent sends the user the connectUrl. The user opens it in their browser and authorizes GitHub access via OAuth. This is the only step that requires human interaction.
Agent says: "Please open this link to connect your GitHub account:"
https://brigs.ai/connect/coral-fox-92
While the user is authorizing, the agent polls the status endpoint every 3–5 seconds. Once integrationConnected is true, the response includes the next action.
GET https://api.brigs.ai/ephemeral/sessions/coral-fox-92/status
Response (after GitHub connected):
{
"slug": "coral-fox-92",
"status": "active",
"integrationConnected": true,
"repoAdded": false,
"scan": null,
"nextStep": {
"action": "add_repo",
"instruction": "Integration connected. List available repos, then add one.",
"apiCall": "GET /integrations/github/<id>/repos → POST /repos { ... }",
"cliCommand": "brigs repo list --json"
}
}The agent adds a repository and triggers a scan. Both calls use the ephemeral session token as a Bearer token.
# Add a repository
POST https://api.brigs.ai/repos
Authorization: Bearer brigs_eph_abc123...
Content-Type: application/json
{ "integrationId": "<id>", "repos": [{ "id": "<repoId>" }] }
# Trigger scan
POST https://api.brigs.ai/scans
Authorization: Bearer brigs_eph_abc123...
Content-Type: application/json
{ "repoId": "<repoId>" }The agent polls status until scan.status is COMPLETED, then shares the public results URL with the user.
# Status response when scan is complete:
{
"scan": { "id": "scn_...", "status": "COMPLETED" },
"nextStep": {
"action": "view_results",
"instruction": "Scan complete. Share the results URL with the user.",
"apiCall": "GET /public/scan-results/coral-fox-92"
}
}Agent says: "Your security scan is complete! View your results:"
https://brigs.ai/scan-results/coral-fox-92
Agents don't need to hardcode the flow. Every API response tells them exactly what to do next.
Key insight: The nextSteps array on session creation gives the full roadmap. The nextStep on status polling gives the contextual next action based on current progress. Agents should follow nextStep — they never need a state machine.
The nextSteps array in the POST /ephemeral/sessions response provides the full 5-step plan upfront:
"nextSteps": [
{ "step": 1, "action": "connect_vcs", "instruction": "Ask the user to open connectUrl..." },
{ "step": 2, "action": "poll_status", "instruction": "Poll statusUrl every 3-5 seconds..." },
{ "step": 3, "action": "add_repo", "instruction": "GET /integrations/github to find..." },
{ "step": 4, "action": "trigger_scan", "instruction": "POST /scans with { repoId }..." },
{ "step": 5, "action": "poll_results", "instruction": "Poll statusUrl until scan complete..." }
]The nextStep object in the GET /ephemeral/sessions/:slug/status response adapts to current state:
"nextStep": {
"action": "connect_vcs",
"instruction": "User needs to connect GitHub. Send them to the connect URL."
}"nextStep": {
"action": "add_repo",
"instruction": "Integration connected. List available repos, then add one.",
"apiCall": "GET /integrations/github/<id>/repos → POST /repos { ... }",
"cliCommand": "brigs repo list --json"
}"nextStep": {
"action": "trigger_scan",
"instruction": "Repo added. Trigger a scan.",
"apiCall": "POST /scans { repoId: \"<id>\" }",
"cliCommand": "brigs scan run --json"
}"nextStep": {
"action": "view_results",
"instruction": "Scan complete. Share the results URL with the user.",
"apiCall": "GET /public/scan-results/<slug>",
"cliCommand": "brigs posture --json"
}Every nextStep response includes both an apiCall and a cliCommand. Agents can choose whichever is more convenient for their environment.
--json on all commandsbrigs agent-scan . works offlineSet the ephemeral token as BRIGS_API_KEY to use CLI commands within an ephemeral session:
export BRIGS_API_KEY=brigs_eph_abc123... brigs repo list --json # list available repos brigs scan run --json # trigger scan brigs posture --json # view posture score brigs finding list --json # list findings
GitHub authorization is the one human-in-the-loop step. OAuth requires the user to consent in their browser — the agent cannot bypass this.
Agent sends the connect URL
The connectUrl from the session creation response points to a branded landing page.
User opens the page
The connect page explains what Brigs is, what permissions are requested, and shows a "Connect GitHub" button.
GitHub OAuth
User authorizes the Brigs GitHub App. Permissions: repo + read:org.
Success page
Redirected to a success page that says "Go back to your AI assistant". The integration is now stored on the shadow org.
The agent polls the status endpoint every 3–5 seconds. The integrationConnected field flips to true once the OAuth callback completes:
# Poll loop (pseudocode)
while true:
response = GET /ephemeral/sessions/<slug>/status
if response.integrationConnected:
break
sleep(4)Ephemeral sessions have a 72-hour lifetime with three possible states.
┌──────────┐ 72h TTL ┌──────────┐
│ active │ ──────────── │ expired │
└──────────┘ └──────────┘
│ │
│ DELETE /sessions/:slug │ account conversion
▼ ▼
┌───────────┐ ┌──────────┐
│ destroyed │ │ claimed │
└───────────┘ └──────────┘
The default state. Full API access with the ephemeral token. Lasts 72 hours from creation.
After 72 hours, the session expires automatically. Results remain visible with an "expired" banner on the public results page. No new scans can be triggered.
Explicitly deleted via DELETE /ephemeral/sessions/:slug. Data is permanently removed by the cleanup worker within 24 hours.
User created an account and claimed the session. The shadow org becomes a permanent organization, and all scan data is preserved.
Every ephemeral session creates a shadow organization behind the scenes. This org is invisible to the user until they create an account.
When POST /ephemeral/sessions is called, a new organization is created with isEphemeral: true and the Free plan. The session slug is used as the org name (e.g., "coral-fox-92").
When the first user creates an account and claims the session, they become the org owner. isEphemeral flips to false. All existing data (repos, scans, findings, posture scores) is preserved.
If a subsequent user tries to claim a session that's already owned, they get a pending membership request. The existing org owner must approve or deny the request from their dashboard.
Ephemeral sessions produce shareable public results. The API and web page carefully scope what's exposed.
GET /public/scan-results/:slug — no authentication required.
GET https://api.brigs.ai/public/scan-results/coral-fox-92
{
"session": { "slug": "coral-fox-92", "status": "active", ... },
"repo": { "provider": "GITHUB" },
"scan": { "status": "COMPLETED", ... },
"posture": {
"overallScore": 72,
"frameworks": {
"OWASP_AGENTIC": { "score": 68, "status": "PARTIAL", "criteriaCount": 10, "passingCount": 7 },
"SOC2": { "score": 80, "status": "PARTIAL", "criteriaCount": 8, "passingCount": 6 }
}
},
"findings": {
"summary": { "critical": 1, "high": 3, "medium": 5, "low": 2 },
"items": [
{ "controlKey": "AGENT_TOOL_ALLOWLIST", "severity": "CRITICAL", "status": "OPEN", "summary": "..." }
]
}
}Ephemeral sessions have strict limits. Create an account to unlock more.
| Resource | Ephemeral | Free | Team |
|---|---|---|---|
| Repositories | 1 | 3 | Unlimited |
| Scans | 1 | Unlimited | Unlimited |
| Session Lifetime | 72 hours | N/A | N/A |
| Rate Limit (per hour) | 5 sessions/IP | 100 req/min | 500 req/min |
| Rate Limit (per day) | 10 sessions/IP | 1,000 req/day | 10,000 req/day |
| Remediation PRs | No | Yes | Yes |
| Evidence Export | No | Yes | Yes |
See pricing for full plan details.
Ephemeral sessions are designed with abuse prevention and data privacy as first-class concerns.
Ephemeral tokens (brigs_eph_) are cryptographically random (32 bytes, base64url). Only the SHA-256 hash is stored in the database. The plaintext token is shown once at session creation and never stored.
Session creation is rate-limited per IP: 5 sessions/hour, 10 sessions/day. A global cap prevents mass session creation.
If the same GitHub user authorizes multiple ephemeral sessions, existing sessions are reused to prevent abuse and wasted resources. Dedup is based on the VCS identity, not the IP address.
Source code is cloned to a temporary directory, scanned, and immediately deleted. Only compliance metadata (scores, control evaluations, finding summaries) is retained. No source code is ever stored permanently or exposed publicly.