Skip to main content

Quickstart

This guide walks through the complete path from onboarding to production-ready API usage.

Prefer working in a language SDK? See SDKs. For concepts, errors, and pagination, see the Developer Guide.

1. Create your organization​

POST /auth/register
Content-Type: application/json

{
  "organizationName": "Acme Ltd",
  "email": "owner@acme.com"
}

2. Sign in with a one-time code​

Request a code:

POST /auth/request-code
Content-Type: application/json

{ "email": "owner@acme.com" }

Verify and receive a JWT:

POST /auth/verify
Content-Type: application/json

{ "email": "owner@acme.com", "code": "482916" }

The response includes accessToken. Use Authorization: Bearer <jwt> for Console and organization API calls.

3. Review your workspace​

After login, open Console and verify:

  • Current signed-in user (GET /me)
  • Workspace settings (GET /settings)
  • Usage and plan status (GET /v1/usage)

This confirms your workspace context before you define governance rules.

4. Understand credentials​

  • Use JWT for interactive Console workflows.
  • Use API keys for machine-to-machine calls.

Machine clients should send Authorization: Bearer <api-key> on protected API requests.

For complete role and scope details, see Auth and Access.

5. Invite members​

Workspace owners can invite additional members from the dashboard:

POST /members
Authorization: Bearer <jwt>
Content-Type: application/json
{
  "email": "billing-admin@acme.com",
  "role": "billing_admin"
}

Allowed role values: billing_admin, user.

6. Create a group​

Create a group that represents the approvers for a workflow:

POST /v1/groups
Authorization: Bearer <jwt-or-api-key>
Content-Type: application/json
{
  "name": "payments",
  "approvers": "finance-lead@acme.com,owner@acme.com"
}

7. Create an asset​

Define the asset or action you want to govern and assign it to a group:

POST /v1/assets
Authorization: Bearer <jwt-or-api-key>
Content-Type: application/json
{
  "name": "invoice-agent",
  "environment": "sandbox",
  "group": "payments",
  "definition": {
    "currency": "USD",
    "files": ["invoice.pdf"],
    "recipient": "vendor-42",
    "risk": {
      "score": 0.82,
      "approved": true
    }
  }
}

8. Create your first policy​

In the policy builder, choose the action and define the rule:

  • Name: Require approval for high-value payments
  • Action: payment.execute
  • Rule: amount > 5000
  • Decision: approval_required

Equivalent API payload:

POST /v1/policies
Authorization: Bearer <jwt-or-api-key>
Content-Type: application/json
{
  "name": "Require approval for high-value payments",
  "action": "payment.execute",
  "decision": "approval_required",
  "condition": {
    "field": "amount",
    "operator": ">",
    "value": 5000
  }
}

9. Run a decision​

Applications call /v1/evaluate with a stable operation_id. SDKs wrap this call; use the raw endpoint only for a client without an SDK. Replace the asset ID with one from your Console.

POST /v1/evaluate
Authorization: Bearer opk_live_...
Content-Type: application/json
{
  "version": "v1",
  "asset": { "id": "ast_e8f1a2c3" },
  "operation_id": "invoice-2026-001",
  "transport": { "kind": "http" },
  "metadata": {
    "operation": "payment.execute",
    "amount": 12000,
    "environment": "production"
  }
}

10. Try the Decision Playground​

The playground lets you test policy behavior without SDK setup:

POST /v1/playground/decision
Authorization: Bearer opk_live_...

Example request:

{
  "workflow": "invoice-payment",
  "asset": "invoice-agent",
  "action": "payment.execute",
  "amount": 12000
}

Expected result with the policy above:

{
  "decision": "approval_required",
  "decisionId": "dec_...",
  "reason": "policy_matched",
  "policyId": "pol_..."
}

If no policy matches, the default response is deny.

11. Resolve approvals when required​

When a decision result is approval_required, use Approvals in Console or call:

GET /v1/approvals
POST /v1/approvals/{id}/approve
POST /v1/approvals/{id}/reject
Authorization: Bearer <jwt-or-api-key>

12. Create and use API keys​

Create key:

POST /v1/api-keys
Authorization: Bearer <jwt>
Content-Type: application/json
{
  "name": "Production Agent Key",
  "scopes": ["decision:run", "assets:read", "policies:read", "usage:read"]
}

Use key:

Authorization: Bearer <api-key>

Track usage:

GET /v1/usage
Authorization: Bearer <jwt-or-api-key>

Next steps​