Persona playbooks

Step-by-step first success for every company role that touches Unveilr. Use the same origin; only the credential and primary APIs change.

export UNVEILR_API=https://guard.unveilr.ai
export UNVEILR_CONSOLE=https://guard.unveilr.ai

Persona	Surface	Auth	First success
Developer	CLI / IDE / PR	None → token	Offline scan; optional upload
AppSec / GRC	Console + API	SSO JWT	Triage + export evidence
Tenant admin	Settings + API	SSO admin	Mint `uvt_`; connect GitHub
Platform super admin	Manage tenants	Super-admin SSO	Provision org + invite
CI / CD	Action / CLI	Service `uvt_`	Observe on PR
Agent / runtime	Gateway / govern	Agent `uvt_`	Allow/deny + evidence

Developer

Goal: See AI risk locally without blocking the team.

Install a checksummed partner binary (or make install with repo access). The public CDN (get.unveilr.ai) is after GA — see Installation.

unveilr --version

Scan offline (no account):

cd your-repo
unveilr scan
unveilr scan --json   # IDE / scripts

Optional: upload to the org control plane:

unveilr login --token "$UNVEILR_TOKEN" --api "$UNVEILR_API"
unveilr scan --upload

Add CI in observe mode — see Integrations.

Done when: offline scan prints findings; optional upload appears under Findings in the console.

AppSec / GRC

Goal: Triage risk, inventory AI assets, prove control.

SSO into $UNVEILR_CONSOLE/o/<org-slug>.
Open Overview → Findings → AI Inventory → Compliance → Evidence.
Via API (Bearer = SSO JWT or admin-issued token):

# Open findings (cursor-paginated)
curl -fsS "$UNVEILR_API/v1/findings?limit=50&status=open" \
  -H "Authorization: Bearer $TOKEN"

# Org AI-BOM (CycloneDX)
curl -fsS "$UNVEILR_API/v1/aibom/cyclonedx" \
  -H "Authorization: Bearer $TOKEN" -o aibom.cdx.json

# Compliance board (example framework slug)
curl -fsS "$UNVEILR_API/v1/compliance/soc2" \
  -H "Authorization: Bearer $TOKEN"

# Evidence export
curl -fsS "$UNVEILR_API/v1/evidence/export?since=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Triage: patch status / assign owner; open tickets via Integrations when configured.

Done when: you can filter findings, export CycloneDX, and pull an evidence export for an audit window.

Tenant administrator

Goal: Wire the org — tokens, repos, agents, IdP.

Accept the WorkOS invite; land on /o/<slug>.
Mint a CI token (Settings → API Tokens), scope scan:upload, store in the secret manager — never in git.
Connect GitHub / register repos; confirm a scan lands findings.
Register agents (owner + allowed tools); have a second admin approve.
When ready: Organization Settings → SSO / SCIM setup links.

curl -fsS -X POST "$UNVEILR_API/v1/tokens" \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "content-type: application/json" \
  -d '{"name":"ci","scopes":["scan:upload"],"expiresInDays":90}'

curl -fsS "$UNVEILR_API/v1/org" \
  -H "Authorization: Bearer $ADMIN_JWT"

curl -fsS "$UNVEILR_API/v1/onboarding" \
  -H "Authorization: Bearer $ADMIN_JWT"

Done when: CI secret works for scan --upload, at least one repo is connected, and onboarding checklist progresses.

Platform super administrator

Goal: Provision customer / business-unit tenants (Unveilr-hosted or your private platform).

WorkOS role slug must be super_admin or platform_admin.
Console → Organization Settings → Manage tenants.
Create org + invite tenant admin (they mint their own uvt_ tokens).

curl -fsS "$UNVEILR_API/v1/platform/tenants" \
  -H "Authorization: Bearer $SUPER_JWT"

Ordinary tenant admins receive 403 on /v1/platform/* — that is correct.

Done when: a new org exists and its tenant admin can sign in and mint tokens.

CI / CD

Goal: Observe AI risk on every PR; fail closed only when you choose enforce.

- uses: <action-your-operator-provided>@v1
  with:
    mode: observe
    fail-on: high
    # cli-base-url: only after your operator’s CDN is live
  env:
    UNVEILR_TOKEN: ${{ secrets.UNVEILR_TOKEN }}
    UNVEILR_API: https://guard.unveilr.ai

Or install a partner CLI binary in the job, then unveilr scan / unveilr scan --upload.

Rules

Start in observe; flip enforce per repo when ready.
Prefer unveilr/scan-action so CI does not depend on get.unveilr.ai before GA.
Rotate UNVEILR_TOKEN via Settings → API Tokens.

Done when: a PR run posts results (and optionally uploads) without requiring developers to change their workflow.

Agent / runtime

Goal: Every tool call is admissible — allow or deny with evidence.

Shared setup (~10 min)

Console → Agents → Register (name, owner, allowedTools).
Approve → copy uvt_… (once).
Open On-ramp on the identity for copy-paste snippets.

export UNVEILR_AGENT_TOKEN=uvt_…

Path A — `POST /v1/govern/check` (any HTTP agent)

curl -fsS -X POST "$UNVEILR_API/v1/govern/check" \
  -H "Authorization: Bearer $UNVEILR_AGENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tool":"ledger.query","server":"ledger","arguments":{"sql":"select 1"}}'

Expect "decision":"allow" or "deny" plus evidenceId. Full cookbooks: Govern check.

Path B — MCP Gateway

Point the MCP client at:

https://guard.unveilr.ai/mcp/<tenant>/<server>

with Authorization: Bearer $UNVEILR_AGENT_TOKEN. Start in observe, then enforce. See Govern.

Done when: one allow and one deny appear in Evidence, and revoke kills further calls immediately.

Developer​

AppSec / GRC​

Tenant administrator​

Platform super administrator​

CI / CD​

Agent / runtime​

Shared setup (~10 min)​

Path A — POST /v1/govern/check (any HTTP agent)​

Path B — MCP Gateway​

Related​