CORTEX

Organizations

System-level management of organizations and the users that belong to them.

Common responses

These responses apply across endpoints in this section unless an endpoint documents an additional response.

StatusMeaningBody
200Request succeeded.Endpoint response object.
201Resource created.Created resource object.
400Invalid request.Error envelope.
401Missing or invalid bearer token.Error envelope.
404Resource not found or not visible to the current organization.Error envelope.

Organizations

List organizations

List organizations in the system, paginated. Soft-deleted organizations are hidden by default; pass `isDeleted=true` to fetch only tombstoned orgs (e.g. for a Deleted tab) or `isDeleted=false` to be explicit about the live-only view. Use `search` for a case-insensitive substring match on name, and `isSystem` to filter system-orgs vs tenant-orgs. Each row is enriched with the joined plan name, total user count, and tasks created in the last 30 days.

GET/v1/admin/organizations

Query parameters

NameTypeRequiredDescription
searchstringOptionalCase-insensitive substring match on organization name.
isSystembooleanOptionalWhen set, returns only system orgs (true) or only tenant orgs (false). Omit to return both.
isDeletedbooleanOptionalFilters by soft-delete state. `true` returns only tombstoned organizations (Deleted tab); `false` returns only live organizations (Active tab, same as the default); omit to use the live-only default.
cursorstringOptionalOpaque pagination cursor returned in next_cursor of the previous response. Omit to start at the beginning.
limitnumberOptionalMaximum number of items to return. Default 20, max 100.
Example requestbash
curl "https://api.cortex.cognit-dx.com/v1/admin/organizations?search=acme&limit=20" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "data": [
    {
      "id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "name": "Acme",
      "is_system": false,
      "is_suspended": false,
      "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
      "plan_name": "Free",
      "plan_slug": "free",
      "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
      "subscription_status": "active",
      "policy_overrides": {},
      "industry": "saas",
      "primary_language": "en",
      "primary_timezone": "America/New_York",
      "user_count": 12,
      "task_count_last30d": 87,
      "created_at": "2026-05-18T10:24:31.000Z",
      "updated_at": "2026-05-18T10:24:31.000Z",
      "deleted_at": null
    }
  ],
  "total": 1,
  "has_more": false,
  "next_cursor": null
}

Get organization

Return a single organization by ID. Soft-deleted organizations are still returned by this endpoint (with `deletedAt` populated) so operators can inspect tombstones. Returns 404 only when the ID does not exist at all.

GET/v1/admin/organizations/:id

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404Organization not found.`{ error, code: 'not_found' }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme",
  "is_system": false,
  "is_suspended": false,
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "plan_name": "Free",
  "plan_slug": "free",
  "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "subscription_status": "active",
  "policy_overrides": {},
  "industry": "saas",
  "primary_language": "en",
  "primary_timezone": "America/New_York",
  "user_count": 12,
  "task_count_last30d": 87,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z",
  "deleted_at": null
}

Create organization

Create a new organization. The new org is auto-subscribed to the "free" plan; use POST /admin/organizations/:id/subscription/change-plan to move it to a paid plan. The new org has no users — create at least one admin via `POST /admin/organizations/:id/users` before anyone can sign in. The `isSystem` flag is intentionally NOT exposed: system organizations are assigned at seed time and cannot be created through the API.

POST/v1/admin/organizations

Request body

NameTypeRequiredDescription
namestringRequiredOrganization name. Must be unique across the system. 1–255 chars.
industrystringOptionalFree-form industry label (e.g. "saas", "fintech"). Maximum 255 chars. Pass null to clear.
primaryLanguagestringOptionalBCP-47 language tag. Default "en". Maximum 32 chars.
primaryTimezonestringOptionalIANA timezone identifier (e.g. "America/New_York"). Default "UTC". Maximum 64 chars.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme",
    "industry": "saas",
    "primary_timezone": "America/New_York"
  }'

Response codes

StatusMeaningBody
201Organization created.The enriched organization row.
409An organization with that name already exists.`{ error, code: 'duplicate_name' }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
201 Createdjson
{
  "id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme",
  "is_system": false,
  "is_suspended": false,
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "plan_name": "Free",
  "plan_slug": "free",
  "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "subscription_status": "active",
  "policy_overrides": {},
  "industry": "saas",
  "primary_language": "en",
  "primary_timezone": "America/New_York",
  "user_count": 12,
  "task_count_last30d": 87,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z",
  "deleted_at": null
}

Update organization

Patch an organization's editable fields. The request body is strict — passing an unknown field (including `isSystem`, `isSuspended`, or `planId`) returns 400. Toggle suspension via the dedicated suspend/unsuspend routes. Change the plan via POST /admin/organizations/:id/subscription/change-plan.

PATCH/v1/admin/organizations/:id

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.

Request body

NameTypeRequiredDescription
namestringOptionalNew organization name. Must remain unique. 1–255 chars.
industrystringOptionalFree-form industry label. Pass null to clear.
primaryLanguagestringOptionalBCP-47 language tag.
primaryTimezonestringOptionalIANA timezone identifier.
policyOverridesobjectOptionalFree-form JSON object of policy override key/values. Replaces the existing object wholesale.
Example requestbash
curl -X PATCH https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815 \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "fintech",
    "primary_timezone": "Europe/Paris"
  }'

Response codes

StatusMeaningBody
400Strict-body violation — unknown field passed.`{ error, code: 'invalid_request' }`
404Organization not found.`{ error, code: 'not_found' }`
409Either the org is soft-deleted (`organization_deleted`) or the new name is already taken (`duplicate_name`).`{ error, code }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme",
  "is_system": false,
  "is_suspended": false,
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "plan_name": "Free",
  "plan_slug": "free",
  "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "subscription_status": "active",
  "policy_overrides": {},
  "industry": "fintech",
  "primary_language": "en",
  "primary_timezone": "Europe/Paris",
  "user_count": 12,
  "task_count_last30d": 87,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z",
  "deleted_at": null
}

Suspend organization

Mark an organization as suspended. Suspended orgs are blocked from acting on the platform (the runtime auth/policy layer rejects their traffic). Idempotency is not assumed: calling suspend on an already-suspended org returns 409 rather than silently succeeding, so operators see the state they expect. The request body is ignored.

POST/v1/admin/organizations/:id/suspend

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
Example requestbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/suspend \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404Organization not found.`{ error, code: 'not_found' }`
409Either the org is soft-deleted (`organization_deleted`) or it is already suspended (`already_suspended`).`{ error, code }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme",
  "is_system": false,
  "is_suspended": true,
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "plan_name": "Free",
  "plan_slug": "free",
  "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "subscription_status": "active",
  "policy_overrides": {},
  "industry": "saas",
  "primary_language": "en",
  "primary_timezone": "America/New_York",
  "user_count": 12,
  "task_count_last30d": 87,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z",
  "deleted_at": null
}

Unsuspend organization

Reverse a prior suspension. Calling on a non-suspended org returns 409 (`not_suspended`). Calling on a soft-deleted org returns 409 (`organization_deleted`) — restore the org first.

POST/v1/admin/organizations/:id/unsuspend

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
Example requestbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/unsuspend \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404Organization not found.`{ error, code: 'not_found' }`
409Either the org is soft-deleted (`organization_deleted`) or it is not currently suspended (`not_suspended`).`{ error, code }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme",
  "is_system": false,
  "is_suspended": false,
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "plan_name": "Free",
  "plan_slug": "free",
  "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "subscription_status": "active",
  "policy_overrides": {},
  "industry": "saas",
  "primary_language": "en",
  "primary_timezone": "America/New_York",
  "user_count": 12,
  "task_count_last30d": 87,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z",
  "deleted_at": null
}

Delete organization

Soft-delete an organization. Sets `deletedAt` to the current timestamp and forces `suspended` to true so the org immediately stops serving traffic. The org row remains in the database (hidden from default list responses) and can be brought back with `POST /restore`. Calling delete on an already-deleted org returns 409 (`already_deleted`).

DELETE/v1/admin/organizations/:id

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
Example requestbash
curl -X DELETE https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404Organization not found.`{ error, code: 'not_found' }`
409Organization is already soft-deleted.`{ error, code: 'already_deleted' }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme",
  "is_system": false,
  "is_suspended": true,
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "plan_name": "Free",
  "plan_slug": "free",
  "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "subscription_status": "active",
  "policy_overrides": {},
  "industry": "saas",
  "primary_language": "en",
  "primary_timezone": "America/New_York",
  "user_count": 12,
  "task_count_last30d": 87,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z",
  "deleted_at": "2026-05-18T11:02:14.000Z"
}

Restore organization

Reverse a prior soft-delete by clearing `deletedAt`. Does NOT auto-unsuspend: suspension is intentionally orthogonal to soft-delete, so an operator may restore a tombstoned org while keeping it suspended pending review. Calling restore on a non-deleted org returns 409 (`not_deleted`).

POST/v1/admin/organizations/:id/restore

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
Example requestbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/restore \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404Organization not found.`{ error, code: 'not_found' }`
409Organization is not currently deleted.`{ error, code: 'not_deleted' }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme",
  "is_system": false,
  "is_suspended": true,
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "plan_name": "Free",
  "plan_slug": "free",
  "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "subscription_status": "active",
  "policy_overrides": {},
  "industry": "saas",
  "primary_language": "en",
  "primary_timezone": "America/New_York",
  "user_count": 12,
  "task_count_last30d": 87,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z",
  "deleted_at": null
}

Users

List users

List every user belonging to an organization, sorted by email ascending. Each row is enriched with the joined organization name and `is_system` flag, plus `console_role_id` (the assigned console role, null when none). Pagination is not applied — typical org sizes don't warrant it.

GET/v1/admin/organizations/:id/users

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404Organization not found.`{ error }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "data": [
    {
      "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "organization_name": "Acme",
      "organization_is_system": false,
      "first_name": "Amir",
      "last_name": "Khan",
      "display_name": "Amir Khan",
      "email": "amir@acme.test",
      "role": "admin",
      "is_suspended": false,
      "is_developer": false,
      "console_role_id": null,
      "created_at": "2026-05-18T10:24:31.000Z",
      "updated_at": "2026-05-18T10:24:31.000Z"
    },
    {
      "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "organization_name": "Acme",
      "organization_is_system": false,
      "first_name": "Jane",
      "last_name": "Cole",
      "display_name": "Jane Cole",
      "email": "jane@acme.test",
      "role": "member",
      "is_suspended": false,
      "is_developer": false,
      "console_role_id": null,
      "created_at": "2026-05-18T10:24:31.000Z",
      "updated_at": "2026-05-18T10:24:31.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 0
}

Create user

Provision a new user inside an organization. The server generates a strong one-time password and returns it in the response as plaintext — it is never persisted in plaintext and never returned again. Capture this value at the call site and share it with the user out-of-band (email, secure channel). The new user can change it after first sign-in.

POST/v1/admin/organizations/:id/users

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.

Request body

NameTypeRequiredDescription
firstNamestringRequiredGiven name. 1–255 chars.
lastNamestringRequiredFamily name. 1–255 chars.
displayNamestringOptionalHow the user should be addressed in UIs. Defaults to `"{firstName} {lastName}"` when omitted.
emailstringRequiredLogin email. Lowercased and trimmed server-side. Must be globally unique across all orgs.
rolestringOptionalOne of `admin` or `member`. Default `member`.
isDeveloperbooleanOptionalGrant developer access for developer-gated tools and APIs. Default `false`.
Example requestbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Cole",
    "email": "jane@acme.test",
    "role": "member",
    "is_developer": true
  }'

Response codes

StatusMeaningBody
201User created.`{ user, password }` — password is plaintext, returned exactly once.
404Organization not found.`{ error }`
409A user with that email already exists somewhere in the system.`{ error }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
201 Createdjson
{
  "user": {
    "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
    "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
    "first_name": "Jane",
    "last_name": "Cole",
    "display_name": "Jane Cole",
    "email": "jane@acme.test",
    "role": "member",
    "is_suspended": false,
    "is_developer": true,
    "created_at": "2026-05-18T10:24:31.000Z",
    "updated_at": "2026-05-18T10:24:31.000Z"
  },
  "password": "Pq7$mZ2v!nB9k8wL"
}

Get user

Fetch a single user, asserting they belong to the named organization. If the user exists but belongs to a different org, the response is 404 (same as if the user didn't exist) so cross-org probes can't enumerate IDs. Returns the enriched user row.

GET/v1/admin/organizations/:id/users/:userId

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
userIdstringRequiredThe user's UUID.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404User not found in this organization.`{ error }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "organization_name": "Acme",
  "organization_is_system": false,
  "first_name": "Jane",
  "last_name": "Cole",
  "display_name": "Jane Cole",
  "email": "jane@acme.test",
  "role": "member",
  "is_suspended": false,
  "is_developer": false,
  "console_role_id": null,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z"
}

Update user

Update a user's display fields, role, developer-access flag, or console role. Two guards apply: (1) you cannot demote yourself from `admin` — that has to come from another admin; (2) you cannot demote the last active admin of the organization (the org would be left without anyone able to manage it). Both violations return 409. `consoleRoleId` assigns (or, passed `null`, clears) the user's console role — see Console roles in Authentication; it's accepted only for users of the system organization and returns 400 `validation_error` otherwise. A system-organization member must always keep a console role: a patch that would leave a non-admin without one (clearing the role, or demoting an admin who has none) returns 400 — suspend the user to revoke console access instead.

PATCH/v1/admin/organizations/:id/users/:userId

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
userIdstringRequiredThe user's UUID.

Request body

NameTypeRequiredDescription
firstNamestringOptionalGiven name. 1–255 chars.
lastNamestringOptionalFamily name. 1–255 chars.
displayNamestring | nullOptionalHow the user is addressed in UIs. Pass `null` to reset it to the `first_name + last_name` default.
rolestringOptionalOne of `admin` or `member`.
isDeveloperbooleanOptionalGrant (`true`) or revoke (`false`) developer access.
consoleRoleIdstring | nullOptionalUUID of a console role to assign, or `null` to clear it (clearing is rejected for system-org members — they must always hold a role). System-organization users only — see GET /v1/admin/console-roles for the available roles.
Example requestbash
curl -X PATCH https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "display_name": "Jane C.",
    "is_developer": true,
    "console_role_id": "5b1f6a2c-8d3e-4a91-9c7b-2e5f8a1d4c60"
  }'

Response codes

StatusMeaningBody
404User not found in this organization.`{ error }`
400`consoleRoleId` was supplied for a user outside the system organization.`{ error, code: 'validation_error', request_id }`
409Cannot remove your own admin role, or cannot remove the last active admin.`{ error }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "organization_name": "Acme",
  "organization_is_system": false,
  "first_name": "Jane",
  "last_name": "Cole",
  "display_name": "Jane C.",
  "email": "jane@acme.test",
  "role": "admin",
  "is_suspended": false,
  "is_developer": true,
  "console_role_id": "5b1f6a2c-8d3e-4a91-9c7b-2e5f8a1d4c60",
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z"
}

Suspend user

Block a user from signing in or acting on the platform. Two guards apply: (1) you cannot suspend yourself; (2) you cannot suspend the last active admin of the organization. Both violations return 409. The body is ignored.

POST/v1/admin/organizations/:id/users/:userId/suspend

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
userIdstringRequiredThe user's UUID.
Example requestbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b/suspend \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404User not found in this organization.`{ error }`
409Cannot suspend your own user, or cannot suspend the last active admin.`{ error }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "organization_name": "Acme",
  "organization_is_system": false,
  "first_name": "Jane",
  "last_name": "Cole",
  "display_name": "Jane Cole",
  "email": "jane@acme.test",
  "role": "member",
  "is_suspended": true,
  "is_developer": false,
  "console_role_id": null,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z"
}

Unsuspend user

Reverse a prior user suspension. The body is ignored. The endpoint succeeds whether the user is currently suspended or not.

POST/v1/admin/organizations/:id/users/:userId/unsuspend

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
userIdstringRequiredThe user's UUID.
Example requestbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b/unsuspend \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
404User not found in this organization.`{ error }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "organization_name": "Acme",
  "organization_is_system": false,
  "first_name": "Jane",
  "last_name": "Cole",
  "display_name": "Jane Cole",
  "email": "jane@acme.test",
  "role": "member",
  "is_suspended": false,
  "is_developer": false,
  "console_role_id": null,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z"
}

Reset user password

Set a user's password or ask the server to generate a strong temporary password. When the request omits `password`, the generated plaintext password is returned exactly once. When a password is supplied, the response does not echo it back.

POST/v1/admin/organizations/:id/users/:userId/password

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
userIdstringRequiredThe user's UUID.

Request body

NameTypeRequiredDescription
passwordstringOptionalOptional replacement password. Must be at least 12 characters when provided. Omit it to generate a temporary password.
Generate a temporary passwordbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b/password \
  -H "Authorization: Bearer $CORTEX_TOKEN"
Set a specific passwordbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b/password \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "password": "correct horse battery staple" }'

Response codes

StatusMeaningBody
200Password changed.`{ user, password }` — `password` is the generated plaintext value, or `null` when a password was supplied.
404User not found in this organization.`{ error }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "user": {
    "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
    "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
    "organization_name": "Acme",
    "organization_is_system": false,
    "first_name": "Jane",
    "last_name": "Cole",
    "display_name": "Jane Cole",
    "email": "jane@acme.test",
    "role": "member",
    "is_suspended": false,
    "is_developer": false,
    "console_role_id": null,
    "created_at": "2026-05-18T10:24:31.000Z",
    "updated_at": "2026-05-18T10:24:31.000Z"
  },
  "password": "aD4!k9Zp2$mQ8vNr"
}

Delete user

Soft-delete a user from an organization. Deleted users are hidden from normal user lists and sign-in lookup paths, but the row remains in the database for auditability. Two guards apply: you cannot delete yourself, and you cannot delete the last active admin of the organization.

DELETE/v1/admin/organizations/:id/users/:userId

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
userIdstringRequiredThe user's UUID.
Example requestbash
curl -X DELETE https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
204User soft-deleted.Empty body.
404User not found in this organization.`{ error }`
409Cannot delete your own user, or cannot delete the last active admin.`{ error }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`

Service accounts

List service accounts

List all service accounts that belong to the organization. Returns an `{ items }` envelope. Useful for auditing which non-human principals have API keys in a given tenant.

GET/v1/admin/organizations/:id/service-accounts

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/9f7c9d3a-1234-5678-9abc-def012345678/service-accounts \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404Resource not found in the caller's organization.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "data": [
    {
      "id": "9f7c9d3a-1234-5678-9abc-def012345678",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "name": "deploy-bot",
      "description": "CI/CD pipeline service account.",
      "role": "member",
      "can_mint_cross_org": false,
      "can_access_console": false,
      "is_suspended": false,
      "created_by_user_id": null,
      "created_at": "2026-04-01T09:00:00.000Z",
      "updated_at": "2026-05-10T14:00:00.000Z",
      "last_used_at": "2026-05-21T08:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total": 0
}

Create service account

Create a service account in the target organization. API keys issued to this account inherit its role and permissions. Privileged flags (`can_access_console`, `can_mint_cross_org`) are hardcoded `false` regardless of the request body. Returns 409 `duplicate_name` if a service account with the same name already exists in the org.

POST/v1/admin/organizations/:id/service-accounts

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.

Request body

NameTypeRequiredDescription
namestringRequiredUnique name within the organization (max 120 characters).
descriptionstringOptionalHuman-readable description (max 1000 characters).
rolestringOptionalOne of `member` (default) or `admin`.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/9f7c9d3a-1234-5678-9abc-def012345678/service-accounts \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Sales assistant"}'

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404Resource not found in the caller's organization.`{ error, code, request_id }`
422Request body failed validation.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
201 Createdjson
{
  "id": "b2d4f6a8-e0c2-4b8d-a1e3-5c7d9f1b3e5a",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "reporting-bot",
  "description": "Scheduled reporting pipeline.",
  "role": "member",
  "can_mint_cross_org": false,
  "can_access_console": false,
  "is_suspended": false,
  "created_by_user_id": null,
  "created_at": "2026-05-21T12:00:00.000Z",
  "updated_at": "2026-05-21T12:00:00.000Z",
  "last_used_at": null
}

Get service account

Return a single service account by ID, scoped to the organization. Returns 404 if the service account does not exist or belongs to a different org.

GET/v1/admin/organizations/:id/service-accounts/:saId

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.
saIdstringRequiredThe saId value from the endpoint path.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/9f7c9d3a-1234-5678-9abc-def012345678/service-accounts/e5f6a7b8-9012-3456-789a-bcdef0123456 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404Resource not found in the caller's organization.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "deploy-bot",
  "description": "CI/CD pipeline service account.",
  "role": "member",
  "can_mint_cross_org": false,
  "can_access_console": false,
  "is_suspended": false,
  "created_by_user_id": null,
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-05-10T14:00:00.000Z",
  "last_used_at": "2026-05-21T08:30:00.000Z"
}

Update service account

Update the name, description, role, or suspension state of a service account. All fields are optional. Privileged flags (`can_access_console`, `can_mint_cross_org`) cannot be changed via this endpoint. Returns 409 `duplicate_name` if renaming to a name already in use. Returns 404 if not found.

PATCH/v1/admin/organizations/:id/service-accounts/:saId

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.
saIdstringRequiredThe saId value from the endpoint path.

Request body

NameTypeRequiredDescription
namestringOptionalNew name (max 120 characters). Must be unique within the org.
descriptionstring | nullOptionalUpdated description, or null to clear.
rolestringOptionalOne of `member` or `admin`.
isSuspendedbooleanOptionalSet to `true` to block all API keys belonging to this account.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/9f7c9d3a-1234-5678-9abc-def012345678/service-accounts/e5f6a7b8-9012-3456-789a-bcdef0123456 \
  -X PATCH \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Sales assistant","description":"Created via the docs example.","role":"member","is_suspended":true}'

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404Resource not found in the caller's organization.`{ error, code, request_id }`
422Request body failed validation.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
200 OKjson
{
  "id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "deploy-bot",
  "description": "CI/CD pipeline service account — production only.",
  "role": "member",
  "can_mint_cross_org": false,
  "can_access_console": false,
  "is_suspended": false,
  "created_by_user_id": null,
  "created_at": "2026-04-01T09:00:00.000Z",
  "updated_at": "2026-05-21T14:00:00.000Z",
  "last_used_at": "2026-05-21T08:30:00.000Z"
}

Delete service account

Permanently delete a service account. Returns 409 `has_live_keys` if the account still owns non-revoked API keys — revoke the keys first. Returns 404 if not found.

DELETE/v1/admin/organizations/:id/service-accounts/:saId

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.
saIdstringRequiredThe saId value from the endpoint path.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/9f7c9d3a-1234-5678-9abc-def012345678/service-accounts/e5f6a7b8-9012-3456-789a-bcdef0123456 \
  -X DELETE \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404Resource not found in the caller's organization.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role or the credential cannot reach admin routes.`{ error, code, request_id }`
204 No Contenttext

Departments

List departments

List all departments in the organization, ordered by name. The `parent_department_id` field enables a tree structure — `null` denotes a top-level department.

GET/v1/admin/organizations/:id/departments

Path parameters

NameTypeRequiredDescription
idstringRequiredThe organization's UUID.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/organizations/f1ba15e0-ebe8-4187-afe6-03ccb25b8815/departments \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404Organization not found.`{ error, code: 'not_found' }`
403Admin access required.`{ error, code, request_id }`
200 OKjson
{
  "data": [
    {
      "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "parent_department_id": null,
      "name": "Engineering",
      "description": "Product and platform engineering.",
      "created_at": "2024-03-20T08:00:00.000Z",
      "updated_at": "2024-03-20T08:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Console roles

List console roles

List every console role with its granted sections and current user count. Console roles let a non-admin, system-organization user reach specific platform sections without the blanket access `users.role === "admin"` grants — assign one with the `consoleRoleId` field on Update user. These management routes are themselves gated on the `access` section. See Console roles in Authentication for how sections gate access.

GET/v1/admin/console-roles
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/console-roles \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role and holds no console role mapped to the `access` section.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "data": [
    {
      "id": "5b1f6a2c-8d3e-4a91-9c7b-2e5f8a1d4c60",
      "name": "Operator",
      "sections": [
        "platform",
        "organizations",
        "sales",
        "operations",
        "ai-platform",
        "billing",
        "access"
      ],
      "user_count": 6
    },
    {
      "id": "d4e8f1a3-6c2b-49a7-8e5d-3f9b2c1a7e04",
      "name": "Sales",
      "sections": [
        "sales"
      ],
      "user_count": 1
    }
  ]
}

Create console role

Create a new console role with a name and a set of granted sections. Assign the role to a system-organization user via the `consoleRoleId` field on Update user, or via the dedicated System users endpoints below.

POST/v1/admin/console-roles

Request body

NameTypeRequiredDescription
namestringRequiredUnique role name, case-insensitive.
sectionsarrayRequiredSections to grant (string[], at least one — a role with no sections is rejected with 400). Any of: platform, organizations, sales, operations, ai-platform, billing, access.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/console-roles \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "sections": ["organizations", "operations"]
  }'

Response codes

StatusMeaningBody
201Role created.`{ id, name, sections }`
400Unknown section value.`{ error, code: 'validation_error', request_id }`
409A role with this name already exists.`{ error, code: 'conflict', request_id }`
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role and holds no console role mapped to the `access` section.`{ error, code: 'admin_required', request_id }`
201 Createdjson
{
  "id": "7c2e4f81-9a3b-4d5e-8f60-1b2c3d4e5f60",
  "name": "Support",
  "sections": [
    "operations",
    "organizations"
  ]
}

Update console role

Rename a console role and/or replace its granted sections. `sections`, when sent, replaces the full set atomically — it is not merged with the existing sections.

PATCH/v1/admin/console-roles/:id

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.

Request body

NameTypeRequiredDescription
namestringOptionalNew role name, case-insensitive-unique.
sectionsarrayOptionalFull replacement set of sections (string[], at least one — emptying a role is rejected with 400). Any of: platform, organizations, sales, operations, ai-platform, billing, access.
Example requestbash
curl -X PATCH https://api.cortex.cognit-dx.com/v1/admin/console-roles/7c2e4f81-9a3b-4d5e-8f60-1b2c3d4e5f60 \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sections": ["operations", "organizations", "billing"]
  }'

Response codes

StatusMeaningBody
200Role updated.`{ id, name, sections }`
400Unknown section value.`{ error, code: 'validation_error', request_id }`
404Role not found.`{ error, request_id }`
409A role with this name already exists.`{ error, code: 'conflict', request_id }`
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role and holds no console role mapped to the `access` section.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "id": "7c2e4f81-9a3b-4d5e-8f60-1b2c3d4e5f60",
  "name": "Support",
  "sections": [
    "billing",
    "operations",
    "organizations"
  ]
}

Delete console role

Delete a console role. Any user currently assigned the role is automatically unassigned (`consoleRoleId` is set to null via the foreign key's `ON DELETE SET NULL`) — no user is deleted or suspended as a side effect.

DELETE/v1/admin/console-roles/:id

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.
Example requestbash
curl -X DELETE https://api.cortex.cognit-dx.com/v1/admin/console-roles/7c2e4f81-9a3b-4d5e-8f60-1b2c3d4e5f60 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
204Role deleted. No response body.—
404Role not found.`{ error, request_id }`
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role and holds no console role mapped to the `access` section.`{ error, code: 'admin_required', request_id }`

System users

List system users

List the caller's own (system) organization's users along with their console-role assignment. Gated on the `access` section; the caller's organization is resolved server-side from the credential and verified to be the system organization — a non-system-org caller gets 403, same as any other console-permission denial.

GET/v1/admin/system-users
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/system-users \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
200OK.`{ data }` — `console_role_id`/`console_role` are both null when the user holds no console role.
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role and holds no console role mapped to the `access` section, or the caller's organization is not the system organization.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "data": [
    {
      "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "first_name": "Priya",
      "last_name": "Shah",
      "display_name": "Priya Shah",
      "email": "priya@cortex.internal",
      "role": "user",
      "is_suspended": false,
      "console_role_id": "5b1f6a2c-8d3e-4a91-9c7b-2e5f8a1d4c60",
      "console_role": "Operator"
    },
    {
      "id": "3f9b2c1a-7e04-4d3e-9c7b-2e5f8a1d4c60",
      "first_name": "Sam",
      "last_name": "Seller",
      "display_name": "Sam Seller",
      "email": "sam@cortex.internal",
      "role": "user",
      "is_suspended": false,
      "console_role_id": null,
      "console_role": null
    }
  ]
}

Create system user

Create a user in the caller's own (system) organization. A one-time plaintext password is generated and returned exactly once in the response — it is never persisted in plaintext or returned again. Gated on the `access` section and the caller's organization is verified to be the system organization.

POST/v1/admin/system-users

Request body

NameTypeRequiredDescription
first_namestringRequiredGiven name (1–255 chars).
last_namestringRequiredFamily name (1–255 chars).
emailstringRequiredUnique email within the organization.
rolestringOptionalOrganization role: `admin` or `member` (default `member`). Admins see every console section.
console_role_idstring | nullOptionalConsole role to assign at creation. Required when `role` is `member` — a role-less member would face a console with no sections (400 `validation_error` without it). Optional for admins, who see every section regardless. An unknown id returns 400.
Example requestbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/system-users \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Priya","last_name":"Shah","email":"priya@cortex.internal","role":"member","console_role_id":"5b1f6a2c-8d3e-4a91-9c7b-2e5f8a1d4c60"}'

Response codes

StatusMeaningBody
201Created.`{ user, password }` — `password` is shown only once. The bcrypt hash is never returned.
400Invalid body, or an unknown `console_role_id`.`{ error, code: 'validation_error', request_id }`
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required, or the caller's organization is not the system organization.`{ error, code: 'admin_required', request_id }`
201 Createdjson
{
  "user": {
    "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
    "organization_id": "a1b2c3d4-5e6f-4a91-9c7b-2e5f8a1d4c60",
    "first_name": "Priya",
    "last_name": "Shah",
    "display_name": "Priya Shah",
    "email": "priya@cortex.internal",
    "role": "member",
    "is_suspended": false,
    "console_role_id": null
  },
  "password": "generated-once-copy-now"
}

Update system user

Assign or clear a system-org user's console role and/or toggle suspension. Both fields are optional and independent — send only what you want to change. 404s if `:id` does not resolve to an active user of the caller's (system) organization.

PATCH/v1/admin/system-users/:id

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.

Request body

NameTypeRequiredDescription
console_role_idstring | nullOptionalA console role id to assign, or null to clear. Clearing is rejected with 400 for members — they must always hold a console role (suspend the user to revoke access). An unknown id also returns 400.
is_suspendedbooleanOptionalSuspend (`true`) or unsuspend (`false`) the user. Suspending your own account returns 409.
Example requestbash
curl -X PATCH https://api.cortex.cognit-dx.com/v1/admin/system-users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "console_role_id": "5b1f6a2c-8d3e-4a91-9c7b-2e5f8a1d4c60"
  }'

Response codes

StatusMeaningBody
200User updated.The updated user row.
400Unknown console role id.`{ error, code: 'validation_error', request_id }`
404User not found in the caller's organization.`{ error, request_id }`
409You cannot suspend your own account.`{ error, code: 'conflict', request_id }`
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role and holds no console role mapped to the `access` section, or the caller's organization is not the system organization.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "first_name": "Priya",
  "last_name": "Shah",
  "display_name": "Priya Shah",
  "email": "priya@cortex.internal",
  "role": "user",
  "is_suspended": false,
  "console_role_id": "5b1f6a2c-8d3e-4a91-9c7b-2e5f8a1d4c60"
}

Reset system user password

Reset a system-org user's password. Omit `password` to have one generated server-side — the plaintext value is returned once in the response body and cannot be retrieved again.

POST/v1/admin/system-users/:id/password

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.

Request body

NameTypeRequiredDescription
passwordstringOptionalNew plaintext password, minimum 12 characters. Omit to auto-generate one.
Example requestbash
curl -X POST https://api.cortex.cognit-dx.com/v1/admin/system-users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b/password \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response codes

StatusMeaningBody
200Password reset.`{ password }` — the generated plaintext value, or null when you supplied one.
404User not found in the caller's organization.`{ error, request_id }`
401Missing or invalid credential.`{ error, code, request_id }`
403Admin access required — caller lacks the system admin role and holds no console role mapped to the `access` section, or the caller's organization is not the system organization.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "password": "aD4!k9Zp2$mQ8vNr"
}

Demo organizations

List demo organizations

List every demo organization, most recently created first. Each row is enriched with the creator's display name, the current admin user's email, the wallet balance, and the user count — everything the Demo Center table needs without a follow-up request.

GET/v1/admin/demo-organizations
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/demo-organizations \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
403Caller lacks the system admin role and holds no console role mapped to the `sales` section.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "data": [
    {
      "id": "b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911",
      "name": "Acme Corp - Demo",
      "is_suspended": false,
      "expires_at": "2026-07-29T10:24:31.000Z",
      "created_at": "2026-07-15T10:24:31.000Z",
      "created_by_user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "created_by_name": "Sam Seller",
      "admin_email": "priya@acme-demo.test",
      "wallet_balance_minor": 5000,
      "user_count": 1
    }
  ]
}

Create demo organization

Atomically provision a full demo tenant: the organization, a `demo`-plan subscription, a $50 prepaid wallet (enforcement on), and one admin user — in a single transaction, so a failure partway through leaves no partial rows. The organization name is suffixed with ` - Demo`; if that suffixed name already exists, returns 409 `duplicate_name` before opening the transaction. `expiresAt` defaults to 14 days out when omitted. The admin's password is generated server-side and returned once, in plaintext — it is never recoverable afterward; use Reset admin password to issue a fresh one.

POST/v1/admin/demo-organizations

Request body

NameTypeRequiredDescription
namestringRequiredProspect/company name, before the ` - Demo` suffix is appended. Max 255 characters.
adminFirstNamestringRequiredFirst name for the generated admin user.
adminLastNamestringRequiredLast name for the generated admin user.
adminEmailstringRequiredEmail for the generated admin user. Lowercased on save.
expiresAtstringOptionalISO 8601 timestamp the demo expires at. Defaults to 14 days from creation.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/demo-organizations \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Acme Corp","admin_first_name":"Priya","admin_last_name":"Shah","admin_email":"priya@acme-demo.test"}'

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
409An organization named `<name> - Demo` already exists.`{ error, code: 'duplicate_name' }`
400Request body failed validation.`{ error, code: 'validation_error', request_id }`
403Caller lacks the system admin role and holds no console role mapped to the `sales` section.`{ error, code: 'admin_required', request_id }`
201 Createdjson
{
  "organization": {
    "id": "b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911",
    "name": "Acme Corp - Demo",
    "is_suspended": false,
    "expires_at": "2026-07-29T10:24:31.000Z",
    "created_at": "2026-07-15T10:24:31.000Z",
    "created_by_user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
    "created_by_name": "Sam Seller",
    "admin_email": "priya@acme-demo.test",
    "wallet_balance_minor": 5000,
    "user_count": 1
  },
  "admin": {
    "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
    "email": "priya@acme-demo.test"
  },
  "password": "correct-horse-battery-staple"
}

Get demo organization

Return a single demo organization plus every user in it. Returns 404 — never 403 — if the id doesn't exist or belongs to a real (non-demo) tenant; demo routes are simply blind to ordinary organizations.

GET/v1/admin/demo-organizations/:id

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/demo-organizations/b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404No demo organization with this id.`{ error, code: 'not_found' }`
403Caller lacks the system admin role and holds no console role mapped to the `sales` section.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "organization": {
    "id": "b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911",
    "name": "Acme Corp - Demo",
    "is_suspended": false,
    "expires_at": "2026-07-29T10:24:31.000Z",
    "created_at": "2026-07-15T10:24:31.000Z",
    "created_by_user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
    "created_by_name": "Sam Seller",
    "admin_email": "priya@acme-demo.test",
    "wallet_balance_minor": 5000,
    "user_count": 1
  },
  "users": [
    {
      "id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "organization_id": "b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911",
      "organization_name": "Acme Corp - Demo",
      "organization_is_system": false,
      "first_name": "Priya",
      "last_name": "Shah",
      "display_name": "Priya Shah",
      "email": "priya@acme-demo.test",
      "role": "admin",
      "is_suspended": false,
      "is_developer": false,
      "department_id": null,
      "created_at": "2026-07-15T10:24:31.000Z",
      "updated_at": "2026-07-15T10:24:31.000Z",
      "deleted_at": null
    }
  ]
}

Extend demo organization

Push out a demo organization's expiry. Touches only `expiresAt` — suspension state is untouched, the same split as Suspend/Unsuspend on the plain organizations routes. `expiresAt` must be a future timestamp; the body is strict, so an unrecognized field is also rejected. Returns the updated organization row directly — not wrapped in an `organization` key.

POST/v1/admin/demo-organizations/:id/extend

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.

Request body

NameTypeRequiredDescription
expiresAtstringRequiredISO 8601 timestamp in the future.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/demo-organizations/b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911/extend \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"expires_at":"2026-08-29T10:24:31.000Z"}'

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404No demo organization with this id.`{ error, code: 'not_found' }`
400`expiresAt` is missing, not in the future, or an unrecognized field was included.`{ error, code: 'validation_error', request_id }`
403Caller lacks the system admin role and holds no console role mapped to the `sales` section.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "id": "b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911",
  "name": "Acme Corp - Demo",
  "is_suspended": false,
  "expires_at": "2026-08-29T10:24:31.000Z",
  "created_at": "2026-07-15T10:24:31.000Z",
  "created_by_user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "created_by_name": "Sam Seller",
  "admin_email": "priya@acme-demo.test",
  "wallet_balance_minor": 5000,
  "user_count": 1
}

Reset admin password

Issue a fresh one-time password for a user in a demo organization — the same generated-password flow as Create demo organization. Returns the plaintext password once; it is never recoverable afterward.

POST/v1/admin/demo-organizations/:id/users/:userId/password

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.
userIdstringRequiredThe userId value from the endpoint path.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/demo-organizations/b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911/users/0ce6409a-3bfa-4e2f-883a-5a696b451d8b/password \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404No demo organization with this id, or no such user in it.`{ error, code: 'not_found' }`
403Caller lacks the system admin role and holds no console role mapped to the `sales` section.`{ error, code: 'admin_required', request_id }`
200 OKjson
{
  "password": "correct-horse-battery-staple"
}

Delete demo organization

Soft-delete a demo organization. Like every other :id route on this router, it 404s instead of ever touching a real tenant organization.

DELETE/v1/admin/demo-organizations/:id

Path parameters

NameTypeRequiredDescription
idstringRequiredThe id value from the endpoint path.
Example requestbash
curl https://api.cortex.cognit-dx.com/v1/admin/demo-organizations/b6a1c9e2-4f83-4a1e-9c72-58e0d3b7a911 \
  -X DELETE \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

StatusMeaningBody
401Missing or invalid credential.`{ error, code, request_id }`
404No demo organization with this id.`{ error, code: 'not_found' }`
403Caller lacks the system admin role and holds no console role mapped to the `sales` section.`{ error, code: 'admin_required', request_id }`
204 No Contenttext