Administration

Everything on this page is doable from the dashboard. The endpoints exist for the case where a dashboard is the wrong shape — a platform provisioning a workspace per signup, a CI job minting a key, an install script pairing a CLI.

These endpoints take an admin session token from Sentisec sign-in, not a workspace API key. Sending a workspace key here returns 401.

Workspaces

On these two lookup routes, a workspace id belonging to another organisation returns 404 rather than 403 — the API will not confirm that a foreign id is real. Deletion is a soft delete: the workspace stops accepting traffic and its keys stop working, but its recorded history survives for audit.

API keys

The plaintext key is returned exactly once, in the 201 from the create call. Sentisec stores a hash plus the last four characters, so a refetch returns metadata only — name, creation time, last-used time, last four, revocation time. If the plaintext is lost, mint a new key and revoke the old one.

Revocation takes effect on the next request; there is no propagation delay to wait out.

Upstream credentials

Your provider keys live per workspace, encrypted at rest. The dashboard encrypts them in your browser before they are sent, so the plaintext never traverses the network.

Rotation takes an already-encrypted credential; a body that sends a plaintext field is rejected with 422. If you are automating this outside the dashboard, the encryption material is part of your install configuration — talk to us for the setup.

POST /v1/workspaces/{workspace_id}/rotate-secrets
Content-Type: application/json

{
  "provider": "openai",
  "encrypted_credential": "<ciphertext>"
}

The new credential is live on the next request. In-flight streams finish on the credential they started with.

Connection testing takes provider_id, not provider — a body that sends {"provider": "openai"} is rejected with 422.

POST /v1/workspaces/{workspace_id}/connection-test
Content-Type: application/json

{ "provider_id": "openai" }

The health endpoint reports one of four statuses per provider. They separate "your key is missing" from "that upstream is not available here", which is the same distinction the 401 / 503 split makes at request time:

Pairing a CLI

The pair flow swaps a short, human-typeable code for a workspace key, so a terminal never has to paste one. It is what the dashboard's "pair a CLI" button and the SDK's login command drive.

Redemption is anonymous by design: the code is the proof, it is single-use, and it expires quickly. Minting is rate-limited per user and address, so a burst of start calls returns 429 with Retry-After.

Identity webhook

One signed endpoint receives identity events and provisions a workspace and its first API key when a user or an organisation is created. It is what makes signup-to-first-call work without an operator in the loop.

Delivery is idempotent: a replayed event returns {"status":"duplicate"} and does not mint a second key. An unsigned request is rejected with 400.

// new user — first mint, the key is returned exactly once
{ "status": "ok", "workspace_id": "<uuid>", "api_key": "sk_sentisec_…" }

// new organisation — workspace only
{ "status": "ok", "workspace_id": "<uuid>" }

// replay of an event already processed
{ "status": "duplicate" }

Events other than user and organisation creation, and user deletion, are acknowledged and ignored. See SCIM provisioning for what that means for identity-provider-driven lifecycle.

Related

• Building on Sentisec — the end-to-end provisioning recipe
• RBAC — which role can call what
• Audit and metrics