LAYER 5 · HUMANS & TENANTS

Guides

Four short tasks: create your org, invite teammates with least privilege, change or disable an account, and what to do about a compromised org API key.

Create your org

Registration is self-serve: the /register form (or one API call) creates the org, its machine API key, and your account — already an admin, already logged in.

POST /orgs/register

curl -s https://api.sentnelops.com/orgs/register \
  -H 'content-type: application/json' \
  -d '{"org_name":"Acme","email":"you@acme.dev","password":"<8+ chars>","name":"You"}'
# → { "org_id": "...", "api_key": "snops_key_...", "user": {...}, "token": "<session JWT>" }

The api_key in that response is shown exactly once — only its hash is stored. Put it in a secret manager immediately. It is your machine/CI credential and carries the admin role; humans should log in with their own accounts instead.

Invite your team with least privilege

Settings → Users has the invite form (email, temporary password, role), or use the API. Start everyone at the lowest role that does their job — the hierarchy means you can always promote later, on their next request: auditors and leadership get viewer; engineers shipping agents get developer; reserve security for whoever should approve production agents and decide held approvals (they can suspend anything — that is on-call power); keep admin to one or two people who manage the team itself.

POST /users (admin)

curl -s https://api.sentnelops.com/users \
  -H "Authorization: Bearer <admin session or org api key>" \
  -H 'content-type: application/json' \
  -d '{"email":"sam@acme.dev","password":"<temp, 8+ chars>","role":"security","name":"Sam"}'

Hand the teammate their temporary password out of band; they change it themselves with POST /auth/password after first login.

Change a role or disable an account

Use the role dropdown / Disable button on Settings → Users, or PATCH. Because the account row is re-checked on every request, the change bites on the person's next call — no waiting for a session to expire.

PATCH /users/{id} (admin)

curl -s -X PATCH https://api.sentnelops.com/users/<user-id> \
  -H "Authorization: Bearer <admin credential>" \
  -H 'content-type: application/json' \
  -d '{"role":"viewer"}'          # or {"status":"disabled"}

If the target is your only active admin, the API refuses with 409 cannot remove the last admin — promote a second admin first, then demote or disable the original.

Rotate a compromised org API key

Roadmap gap — there is no key-rotation endpoint today. The API can rotate agent tokens (POST /agents/{id}/rotate), but nothing rotates the org key itself. Treat a leaked org key as a full-admin compromise and act immediately with the workarounds below.

Managed (api.sentnelops.com): contact support to have a new key minted for your org. Until then, remember the key cannot log in as a user or impersonate an agent at the gateway — but it can do everything else, so review the audit log for actions attributed to "api-key".

Self-hosted: the database stores only the key's SHA-256 index, so you can mint a replacement yourself — generate a new snops_key_… value, then overwrite the hash:

psql — replace the org key hash (self-hosted)

-- mint a high-entropy replacement, e.g. "snops_key_" + 24 random urlsafe bytes
UPDATE orgs SET api_key_hash = encode(sha256('<new plaintext key>'), 'hex')
WHERE id = '<your org id>';
-- the old key stops working on its next request; update CI secrets to the new key

Next: Reference