API reference Account
Account
The caller's connected assistants in every organisation they belong to
GET /assistants
The caller's connected assistants in every organisation they belong to: client_name, redirect_host, workspace_name, project_name, role, allow_changes, created_at, last_used_at. mcp_url is the address to add in an assistant, empty while the server has no STACKURITY_BASE_URL (assistants are off).
Responses
Allow or stop changes by one of the caller's assistants
PATCH /assistants/{id}
{"allow_changes": true | false} for one of the caller's assistants (404 for anyone else's). Audited as assistant.update
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Disconnect one of the caller's assistants
DELETE /assistants/{id}
Disconnect one of the caller's assistants: its tokens stop working at once (404 for anyone else's). Audited as assistant.revoke
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Choose the project the dashboard opens with
PUT /auth/default-project
{"project_id": N} (0: all projects): the project the dashboard opens with. GET /auth/me returns it as default_project_id, with projects (the projects the caller can choose), access and project_role
Request body
application/json, required: object
Responses
Your bulk email preferences (hosted installations)
GET /auth/email-preferences
Your choices for bulk email: categories (marketing, vulnerability_news) with subscribed, source and changed_at of the last change, label and description; and locked, the email that cannot be turned off here. 404 on servers that send no bulk email (email_preferences in GET /meta)
Responses
Change your bulk email preferences
PUT /auth/email-preferences
{"marketing": false}, {"vulnerability_news": true} or both: changes your choices at once and answers as GET. Subscribing again lifts a suppression of your address for that category
Request body
application/json, required: object
Responses
Sign in with email and password (starts a session)
POST /auth/login
Session handling
Request body
application/json, required: LoginRequest
| Field | Type | Description |
|---|---|---|
email required | string (email) | |
password required | string (password) |
Responses
| Status | Meaning | Body |
|---|---|---|
2XX | Signed in: the user, and the stackurity_session cookie is set. Or, for an account with a second factor, mfa_required and no session yet. | one of User, MFARequired |
4XX | An error | Error |
5XX | An error | Error |
Sign out (ends the session)
POST /auth/logout
Session handling
Responses
The caller: user, role, organisation, projects and edition
GET /auth/me
The caller: user, role, access, project_role, projects, workspace, workspaces, edition, features, and invite_only (people join by invitation: POST /users is refused)
Responses
Your two-factor methods: passkeys, authenticator app, email codes, recovery codes, and what your organisation requires
GET /auth/mfa
Responses
Remove all your second factors (password)
DELETE /auth/mfa
Request body
application/json, required: object
Responses
Turn on email codes (password): emails a code to confirm
POST /auth/mfa/email
Request body
application/json, required: object
Responses
Turn off email codes (password)
DELETE /auth/mfa/email
Request body
application/json, required: object
Responses
Turn on email codes with the code emailed
POST /auth/mfa/email/confirm
Request body
application/json, required: object
Responses
Second step of a password sign-in: email a six-digit code
POST /auth/mfa/email/send
With the challenge cookie from POST /auth/login, for an account that uses email codes: emails a code valid for 10 minutes; then POST /auth/mfa/verify with it
Responses
Second step of a password sign-in with a passkey: request options
POST /auth/mfa/passkey/begin
After POST /auth/login answered mfa_required with passkey among the methods: answers options for navigator.credentials.get() (the account's passkeys)
Responses
Second step of a password sign-in with a passkey: starts the session
POST /auth/mfa/passkey/finish
{"credential": <PublicKeyCredential JSON>} with the challenge and ceremony cookies: starts the session and answers the user
Request body
application/json, required: object
Responses
Start registering a passkey or security key (password): creation options
POST /auth/mfa/passkeys/begin
Request body
application/json, required: object
Responses
Finish registering a passkey: name it; returns recovery codes for the first factor
POST /auth/mfa/passkeys/finish
Request body
application/json, required: object
Responses
Rename one of your passkeys
PATCH /auth/mfa/passkeys/{id}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Remove one of your passkeys (password)
DELETE /auth/mfa/passkeys/{id}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Replace your recovery codes (password)
POST /auth/mfa/recovery-codes
Request body
application/json, required: object
Responses
Confirm this session with a code from the app or a recovery code
POST /auth/mfa/step-up
Request body
application/json, required: object
Responses
Email a code that confirms this session
POST /auth/mfa/step-up/email/send
Responses
Confirm this session with a passkey: request options
POST /auth/mfa/step-up/passkey/begin
Responses
Confirm this session with a passkey
POST /auth/mfa/step-up/passkey/finish
Request body
application/json, required: object
Responses
Start setting up TOTP (password): secret, otpauth URL and QR code
POST /auth/mfa/totp
Request body
application/json, required: object
Responses
Remove your authenticator app (password)
DELETE /auth/mfa/totp
Request body
application/json, required: object
Responses
Confirm TOTP with a code; returns ten recovery codes once
POST /auth/mfa/totp/confirm
Request body
application/json, required: object
Responses
Second step of a password sign-in: a TOTP or recovery code
POST /auth/mfa/verify
After POST /auth/login answered mfa_required: {"code": "123456"} (or a recovery code) with the challenge cookie starts the session
Request body
application/json, required: MFAVerifyRequest
| Field | Type | Description |
|---|---|---|
code required | string | A 6-digit code from the authenticator app or the email, or one recovery code. |
Responses
Single sign-on callback from the identity provider (licensed edition)
GET /auth/oidc/callback
Responses
Start single sign-on (licensed edition)
GET /auth/oidc/login
Responses
Start a passkey sign-in (no email or password): request options
POST /auth/passkey/begin
Answers options for navigator.credentials.get() (discoverable credentials, user verification required) and sets a short-lived cookie
Responses
Finish a passkey sign-in: starts the session
POST /auth/passkey/finish
{"credential": <PublicKeyCredential JSON>} with the cookie from /auth/passkey/begin: starts the session and answers the user
Request body
application/json, required: object
Responses
Change your own password (current_password, new_password)
POST /auth/password
Change your own password (current_password, new_password). Your other sessions are signed out
Request body
application/json, required: PasswordChangeRequest
| Field | Type | Description |
|---|---|---|
current_password required | string (password) | |
new_password required | string (password) | Must meet the organisation's password rules; otherwise 400 password_too_weak with the rules missed in details. |
revoke_tokens | boolean | Also revoke your API tokens. Default false. |
revoke_assistants | boolean | Also disconnect the AI assistants connected as you. Default true. |
Responses
| Status | Meaning | Body |
|---|---|---|
2XX | Success | PasswordChangeResult |
4XX | An error | Error |
5XX | An error | Error |
Email a password reset link (same answer whether or not the account exists)
POST /auth/password-reset
Request body
application/json, required: object
Responses
Set a new password with a reset link; ends every session
POST /auth/password-reset/confirm
Request body
application/json, required: object
Responses
Whose account a reset link is for, and how many API tokens it has
POST /auth/password-reset/preview
Request body
application/json, required: object
Responses
Your active browser sessions
GET /auth/sessions
Responses
Sign out all your other browser sessions
POST /auth/sessions/revoke-others
Responses
Sign out one of your other browser sessions
DELETE /auth/sessions/{id}
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Your sign-ins through Google, Microsoft or GitHub (hosted edition)
GET /auth/social
Stackurity Cloud (hosted) only. Each configured provider with connected, email, login, created_at, last_used_at; and has_password
Responses
Connect a provider to an existing account from the emailed link (hosted edition)
POST /auth/social/confirm
Stackurity Cloud (hosted) only. {"token"} from the link emailed to the account's address, in the browser that signed in with the provider: connects it and signs in (mfa_required when the account has a second factor)
Request body
application/json, required: object
Responses
Disconnect a provider from your account (hosted edition)
DELETE /auth/social/{provider}
Stackurity Cloud (hosted) only. 409 when it is the only way into an account without a password
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
provider required | path | string | One of google, microsoft, github. |
Responses
Start connecting a provider to your account (hosted edition)
POST /auth/social/{provider}/link
Stackurity Cloud (hosted) only. {"password"} when the account has one; answers redirect_url (the provider). Never for an instance administrator
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
provider required | path | string | One of google, microsoft, github. |
Request body
application/json, required: object
Responses
Find an organisation's single sign-on from an email (hosted edition)
POST /auth/sso/discover
Stackurity Cloud (hosted) only. email. Answers login_url and label for the organisation that verified the address's domain, if its single sign-on is on; otherwise 404
Request body
application/json, required: object
Responses
Ask for a free self-hosted key (hosted edition)
POST /community-keys
Stackurity Cloud (hosted) only. email, name, company (optional), challenge token and accept_terms; emails a one-time link. Limited per address, per email and for the service
Request body
application/json, required: object
Responses
Issue a free key for a self-hosted server (hosted edition)
POST /community-keys/link/confirm
Stackurity Cloud (hosted) only. Same body as the preview; issues a Community key to the signed-in person and answers redirect, the server's /setup/community-key with the key and state in the fragment
Request body
application/json, required: object
Responses
Check where a self-hosted server's key would go (hosted edition)
POST /community-keys/link/preview
Stackurity Cloud (hosted) only. {"return", "state", "server_id"} from a self-hosted server's Get a free key; answers the checked return, host and insecure. Nothing is issued
Request body
application/json, required: object
Responses
Issue a free self-hosted key from the emailed link (hosted edition)
POST /community-keys/verify
Stackurity Cloud (hosted) only. Uses the emailed token once: answers the Community key (key, key_id, email) and emails it
Request body
application/json, required: object
Responses
Approve or deny a device sign-in (the approval page)
POST /device/decision
user_code, decision (approve or deny), workspace_id (the organisation the page showed; 409 if the session switched) and project_id (0: none; admins only). Approving needs the engineer role or above organisation-wide and makes an API token named <client> on <host> (collector role, a year) listed under API tokens; the tool collects it with its next poll. Answers status and, when approved, token. Browser sessions only, with X-Stackurity-CSRF; a request whose Sec-Fetch-Site is not same-origin is refused. Audited as device.approve (with token.create) or device.deny
Request body
application/json, required: object
Responses
What a device sign-in code asks for (the approval page)
POST /device/preview
{"user_code"} (any case, with or without the hyphen): the client (id, name), the host the tool reported, request_ip, requested_at, expires_at, signed_in_as, the session's workspace, your_role, can_approve (or cannot_approve, why not), projects (admins only: where new assets may go), token_name and token_days. 404 for an unknown code, 410 code_used or code_expired. 20 codes per person and 40 per address in 15 minutes (429)
Request body
application/json, required: object
Responses
Open the bulk email preference page from a signed link
POST /email/preferences
{"token"} from a bulk email's link (/email/preferences#...). Changes nothing. Answers kind (preferences or unsubscribe), email (partly hidden), categories and locked; an unsubscribe link answers its category only. 410 link_expired or link_invalid
Request body
application/json, required: object
Responses
Change bulk email preferences from a signed link
POST /email/preferences/update
{"token", "marketing"?, "vulnerability_news"?}. An unsubscribe link can only set its own category to false (403 otherwise); an Email preferences link can change both. Mail clients use the one-click address in the List-Unsubscribe header (RFC 8058), POST /email/preferences/one-click?t=..., outside /api/v1
Request body
application/json, required: object
Responses
Send feedback to the Stackurity team
POST /feedback
Send feedback to the Stackurity team: kind (issue, feature, question; bug and idea still work), message (up to 5000 characters), optional email, page (a path) and viewport, as JSON, or as multipart/form-data with the same fields first and up to three attachment files (PNG, JPEG, WebP or GIF images and PDFs up to 10 MB, MP4 or WebM videos up to 50 MB, 90 MB together; checked by content, images stripped of metadata). The answer has the reference ref (FB-123) when the feedback service gives one. The server adds its version and edition and forwards it to STACKURITY_FEEDBACK_URL; answers 202 when delivered, 502 when the feedback service cannot be reached, and 404 when feedback is turned off (GET /auth/me then has feedback_enabled: false). See network.md
Request body
application/json, required: object
Responses
List the feedback you sent and its status
GET /feedback/mine
Items the caller sent from this installation, newest first: ref (FB-123), kind, summary, attachments, status (received, reviewing, in_progress, fixed, released, wont_fix, duplicate, unknown), status_note, fixed_in, status_at, created_at. Statuses of open items older than five minutes are asked again from the feedback service with each item's status token; check_failed says when that did not work. See network.md
Responses
Allow or deny an assistant's connection (the consent page)
POST /oauth/authorize
The same parameters with decision (allow or deny), workspace_id (the organisation the page showed; 409 if the session switched), project_id (0: the whole organisation), role and allow_changes (default false: read only): answers redirect, the client's redirect URI with a single-use code (2 minutes) or error=access_denied, plus state and iss. A role above the caller's is 403. Audited as assistant.authorize
Request body
application/json, required: object
Responses
The consent page's view of an authorization request
POST /oauth/authorize/preview
The consent page's view of an authorization request (its response_type, client_id, redirect_uri, code_challenge, code_challenge_method, state, scope, resource): the client (name, redirect_host), signed_in_as, the active workspace, the projects and the roles (up to the caller's own) the person may give. 400 with error.redirect (the client's redirect URI with the error) when the request is wrong, or without it when the client or redirect URI cannot be trusted
Request body
application/json, required: object
Responses
The caller's saved views on a dashboard page
GET /saved-views
page (default and only value for now: fixes). Items by name: id, page, name, query (the page's query string), created_at, updated_at
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
page | query | string | One of fixes. |
Responses
Save a view for the caller
POST /saved-views
{"page", "name", "query"}: saves the page's query string under a name (1 to 60 characters); the same name replaces its query. At most 50 views per page
Request body
application/json, required: object
Responses
Delete one of the caller's saved views
DELETE /saved-views/{id}
Another person's view is not found (404)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Start a sign-up (hosted edition)
POST /signup
Stackurity Cloud (hosted) only. Email, name, organisation, password, challenge token (action signup) and accept_terms; answers 202 check_email whatever the email's state
Request body
application/json, required: object
Responses
Finish a sign-up through Google, Microsoft or GitHub (hosted edition)
POST /signup/social
Stackurity Cloud (hosted) only. token, name, organisation, accept_terms, email_notice_version: creates the account (no password), the organisation on its trial, connects the identity and starts a session; answers workspace_id and next
Request body
application/json, required: object
Responses
Who a provider vouched for, before finishing a sign-up (hosted edition)
POST /signup/social/preview
Stackurity Cloud (hosted) only. {"token"} from /signup/social#<token>, in the browser that signed in with Google, Microsoft or GitHub: the verified email, name, provider and colleagues_domain; 410 when expired, used or another browser's
Request body
application/json, required: object
Responses
Verify a sign-up and create the organisation (hosted edition)
POST /signup/verify
Stackurity Cloud (hosted) only. Uses the emailed token once: creates the account and the organisation on its trial, and starts a session
Request body
application/json, required: object
Responses
The caller's linked Slack accounts in the current organisation
GET /slack/links
The caller's linked Slack accounts in the current organisation (team_id, team_name, slack_user_id, slack_user_name, created_at, last_used_at)
Responses
Link a Slack account to the caller
POST /slack/links/confirm
{"token"}: links that Slack account to the caller (single use). 410 as above; 409 when it is linked to another account, which has to unlink it first. API tokens get 403. Audited as slack_link.create
Request body
application/json, required: object
Responses
The Slack account a one-time link would link
POST /slack/links/preview
{"token"} from the link offered in Slack: the Slack account it would link, linked_to_you, linked_to_other, and signed_in_as. 410: the link was used, expired (15 minutes) or belongs to another organisation
Request body
application/json, required: object
Responses
Unlink one of the caller's Slack accounts (404 for anyone else's)
DELETE /slack/links/{id}
Unlink one of the caller's Slack accounts (404 for anyone else's). Audited as slack_link.delete
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
API tokens (yours; admins: all)
GET /tokens
Personal tokens (admins: all tokens and collector tokens). A collector token can name a project_id: assets it creates are added to that project (the first-run flow's repository step)
Responses
Create an API token (shown once)
POST /tokens
Personal tokens (admins: all tokens and collector tokens). A collector token can name a project_id: assets it creates are added to that project (the first-run flow's repository step). On Stackurity Cloud, while the organisation requires single sign-on, an API token of anyone but the owner cannot create tokens (403 sso_required)
Request body
application/json, required: object
Responses
Revoke an API token
DELETE /tokens/{id}
Personal tokens (admins: all tokens and collector tokens). A collector token can name a project_id: assets it creates are added to that project (the first-run flow's repository step)
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
The organisations (workspaces) the caller belongs to
GET /workspaces
Responses
Switch the session to another of the caller's organisations
POST /workspaces/{id}/activate
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object