Skip to main content

Trial & Onboarding API

Two read-only endpoints that back the trial banner and the setup checklist in the UI. Both are tenant-scoped and require the tenant:read permission.

Trial status​

GET /api/v1/tenants/{tenantID}/trial

While a trial is running:

{
  "active": true,
  "ends_at": "2026-04-10T00:00:00Z",
  "days_remaining": 14
}

days_remaining is rounded up, so a trial with 6 hours left reports 1, not 0.

When there is no active trial — never started, or already ended:

{
  "active": false
}
active: false is not only "expired"

The same response is returned for a tenant that never had a trial (for example one created under a paid agreement) and for one whose trial has ended. The response carries no other fields in this state — do not read ends_at or days_remaining without checking active first.

What happens when a trial ends​

When the trial end date passes, the tenant is suspended. Subsequent API calls return:

{
  "error": "tenant_suspended",
  "reason": "trial_expired"
}

with HTTP 403. This is a hard stop, not a reduced-capability mode — there is no free tier to fall back to. Subscribe before the end date to avoid an interruption; if you are already suspended, contact your account contact or complete checkout to be reinstated.

Onboarding checklist​

GET /api/v1/tenants/{tenantID}/onboarding

Returns four setup steps and overall progress:

{
  "steps": [
    { "id": "add_credentials", "label": "Add cloud credentials",   "completed": true  },
    { "id": "run_discovery",   "label": "Run first discovery job", "completed": true  },
    { "id": "view_compliance", "label": "View compliance report",  "completed": false },
    { "id": "invite_team",     "label": "Invite a team member",    "completed": false }
  ],
  "percent_complete": 50
}

Each step is computed live from your tenant's actual data — nothing is stored as a flag you can set, and the steps cannot be dismissed through this API:

StepMarked complete when
add_credentialsAt least one credential exists for the tenant
run_discoveryAny discovery job or agentless scan has reached completed
view_complianceThe tenant has at least one finding
invite_teamAt least one invitation has been accepted (sending is not enough)

percent_complete is the share of completed steps, rounded to the nearest integer — with four steps it moves in increments of 25.

view_compliance follows from discovery

It is satisfied by the existence of findings, which a completed discovery normally produces. If it is still incomplete after a successful discovery, the scan likely produced no findings — check the compliance packs enabled for the workspace.