Access operations. Substrio docs

`account`

`account.invite_page`

Read the page an invited person joins an account on (text/html).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op account.invite_page

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op account.invite_page

`auth`

`auth.agent_token.create`

Create an agent token that acts as the signed-in user; the secret is returned once.

Route: POST /v1/_auth/agent_tokens
Auth: App key or user session; your security rules apply none
MCP tool: substrio_auth_agent_token_create
CLI: substrio op auth.agent_token.create

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	Yes
`expires_in_days`	body	`integer`	No	Minimum 1.

Response

Field	Type	Present	Description
`id`	`string`	Always
`name`	`string`	Always
`token`	`string`	When set	The secret, returned once.
`created_at`	`integer`	Always
`expires_at`	`integer`	Always	0: never.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/agent_tokens" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name"}'

`auth.agent_token.list`

List the signed-in user's agent tokens; a token's secret is shown only when it is created (auth.agent_token.create).

Route: GET /v1/_auth/agent_tokens
Auth: App key or user session; your security rules apply none
MCP tool: substrio_auth_agent_token_list
CLI: substrio op auth.agent_token.list

Parameters

No parameters.

Response

Field	Type	Present	Description
`tokens`	`array of object`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/agent_tokens" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.agent_token.revoke`

Revoke one of the signed-in user's agent tokens.

Route: DELETE /v1/_auth/agent_tokens/{id}
Auth: App key or user session; your security rules apply none
MCP tool: substrio_auth_agent_token_revoke
CLI: substrio op auth.agent_token.revoke

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The agent token's id, as `auth.agent_token.list` returned it.

Response

A successful 204 No Content response has no body.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_auth/agent_tokens/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.connection.list`

List the apps the signed-in person connected to their login.

Route: GET /v1/_auth/connections
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.connection.list

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/connections" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.connection.revoke`

Disconnect an app from the signed-in person's login; its sessions end and it must ask again.

Route: DELETE /v1/_auth/connections/{app}
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.connection.revoke

Parameters

Name	In	Type	Required	Description
`app`	path	`string`	Yes	The connected app's slug.

Response

A successful 204 No Content response has no body.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_auth/connections/$APP" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.devices`

Count the signed-in person's remembered devices: each signs in with the authenticator code and no email until it ends (30 days, or every session of the person ending).

Route: GET /v1/_auth/devices
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.devices

Parameters

No parameters.

Response

Field	Type	Present	Description
`count`	`integer`	Always	Minimum 0.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/devices" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.devices.forget`

Forget every remembered device of the signed-in person: each signs in by the email code again. No session ends.

Route: POST /v1/_auth/devices/forget
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.devices.forget

Parameters

No parameters.

Response

A successful 204 No Content response has no body.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/devices/forget" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

Mail a short code and a link that prove an address; nobody need be signed in. One pair an address: asked again while it lives, the same code and link are mailed again (every mail sent works) and its life starts over; a spent, expired or locked pair gives way to a new one. Paced by the app's request interval. Answers {accepted, expires_at} whether or not anyone holds the address. On a device remembered for the person the address names (the substrio_device cookie auth.mfa set), their 2FA on, no mail is sent: {accepted, expires_at, mfa_required, challenge}, finished by auth.mfa with the authenticator code.

Route: POST /v1/_auth/email/code_request
Auth: App key or user session; your security rules apply none
MCP tool: substrio_auth_email_code_request
CLI: substrio op auth.email.code_request

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	Yes
`turnstile_token`	body	`string`	No	On the platform host's identity app: the token of the Cloudflare Turnstile check the page showed (`auth.turnstile` names its site key); refused TURNSTILE_REQUIRED without one while the platform sets turnstile_secret.

Response

Field	Type	Present	Description
`accepted`	`any`	Always
`expires_at`	`integer`	Always	Unix seconds: the code's end, or the challenge's.
`mfa_required`	`any`	When set	A remembered device: no email was sent; answer the challenge with `auth.mfa`.
`challenge`	`string`	When set	With mfa_required: the challenge `auth.mfa` takes with the authenticator code.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/email/code_request" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"email"}'

`auth.email.code_verify`

Prove an address with its mailed code (email and code) or its link (token): the person holding it, made when nobody does, is verified. Answers {verified, email, user_id, created, password_grant?}; a code or link that proves nothing is 400 with its reason (MISSING, USED, EXPIRED, TOO_MANY_ATTEMPTS, WRONG and attempts_remaining).

Route: POST /v1/_auth/email/code_verify
Auth: App key or user session; your security rules apply none
MCP tool: substrio_auth_email_code_verify
CLI: substrio op auth.email.code_verify

Parameters

Name	In	Type	Required
`email`	body	`string`	No
`code`	body	`string`	No
`token`	body	`string`	No

Response

Field	Type	Present	Description
`verified`	`any`	Always
`email`	`string`	Always
`user_id`	`integer`	Always
`created`	`boolean`	Always
`password_grant`	`string`	When set	A one-time password reset token; absent for a suspended or deleted person.
`token`	`string`	When set	A session: the code proves the mailbox, so the person is signed in; absent when 2FA is due.
`keyring`	`string`	When set
`mfa`	`object`	When set	The 2FA step due instead of a session: the challenge to answer with `auth.mfa`.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/email/code_verify" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.email.verify`

Verify an email with the token from its link.

Route: POST /v1/_auth/email/verify
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.email.verify

Parameters

Name	In	Type	Required	Description
`token`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/email/verify" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"token"}'

`auth.email.verify_request`

Mail the signed-in user a link that verifies their email.

Route: POST /v1/_auth/email/verify_request
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.email.verify_request

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/email/verify_request" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.github`

Authenticate with GitHub OAuth.

Route: POST /v1/_auth/github
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.github

Parameters

Name	In	Type	Required	Description
`code`	body	`string`	No
`token`	body	`string`	No

Response

Field	Type	Present	Description
`success`	`any`	Always
`user_id`	`integer`	Always
`token`	`string`	Always
`provider`	`any`	Always
`email`	`string`	Always
`name`	`string`	Always
`keyring`	`string`	Always	Matches `^0x[0-9a-fA-F]{16}$`.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/github" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.google`

Authenticate with Google OAuth.

Route: POST /v1/_auth/google
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.google

Parameters

Name	In	Type	Required	Description
`credential`	body	`string`	Yes

Response

Field	Type	Present
`success`	`any`	Always
`user_id`	`integer`	Always
`token`	`string`	Always
`email`	`string`	Always
`name`	`string`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/google" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credential":"credential"}'

`auth.link.redeem`

For the console: spend a one-time console link (token, from the url's #link fragment) and sign its person in at the identity app, marked: an irreversible call waits for an approval and it decides none (CONSOLE_LINK_STEP_UP) until the person signs in again by the email code or 2FA. Answers {user_id, account_id, token, keyring} as auth.email.code_verify signs in, or the 2FA step due under mfa; a link that signs nobody in is refused CONSOLE_LINK_UNKNOWN (made up, or replaced by a newer link), CONSOLE_LINK_USED or CONSOLE_LINK_EXPIRED.

Route: POST /v1/_auth/link/redeem
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.link.redeem

Parameters

Name	In	Type	Required	Description
`token`	body	`string`	Yes

Response

Field	Type	Present	Description
`user_id`	`integer`	Always
`account_id`	`integer`	Always	The account the agent acts in; 0 when the link names none.
`token`	`string`	When set	The person's session; absent when 2FA is due.
`keyring`	`string`	When set
`mfa`	`object`	When set	The 2FA step due instead of a session: the challenge to answer with `auth.mfa`.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/link/redeem" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"token"}'

`auth.login`

Authenticate a user.

Route: POST /v1/_auth/login
POST /v1/auth/login
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.login

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	Yes
`password`	body	`string`	Yes

Response

Field	Type	Present	Description
`success`	`any`	Always
`user_id`	`integer`	Always
`token`	`string`	Always
`keyring`	`string`	Always	Matches `^0x[0-9a-fA-F]{16}$`.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/login" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"email","password":"password"}'

`auth.login.set`

Join the shared login ([login]): make the app a client of the identity app with a callback on each of its hosts.

Route: PUT /v1/_auth/login
Auth: App key tenant
MCP tool: substrio_auth_login_set
CLI: substrio op auth.login.set

Parameters

Name	In	Type	Required	Description
`enabled`	body	`boolean`	No	false removes the client [login] made.
`next`	body	`string`	No	Where /_/login sends people when ?next= is absent or unsafe; default /.
`scopes`	body	`array of "openid" \| "email"`	No	Default both; openid is required.
`redirect_uris`	body	`array of string`	No	Extra callback URIs, e.g. http://localhost:4321/_/login/callback.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_auth/login" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.logout`

End this session; its token stops working at once, and this browser's substrio_session cookie ends and is cleared (a remembered device stays).

Route: POST /v1/_auth/logout
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.logout

Parameters

No parameters.

Response

A successful 204 No Content response has no body.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/logout" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.logout_all`

End every session of the signed-in user, this one included.

Route: POST /v1/_auth/logout_all
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.logout_all

Parameters

No parameters.

Response

A successful 204 No Content response has no body.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/logout_all" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.logout_here`

End this session and this browser's stay on this site; the person stays signed in at the identity app and at every other app.

Route: POST /v1/_auth/logout_here
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.logout_here

Parameters

No parameters.

Response

A successful 204 No Content response has no body.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/logout_here" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.me`

Read the signed-in user.

Route: GET /v1/_auth/me
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.me

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/me" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.me.delete`

Erase the signed-in user and their auth records; dry_run checks only.

Route: DELETE /v1/_auth/me
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.me.delete

Parameters

Name	In	Type	Required	Description
`dry_run`	query	`boolean`	No	true checks whether deletion is allowed without erasing anything.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_auth/me" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.me.update`

Edit the signed-in person's profile. The name can always be changed; each member of fields must be marked "self": true in the app's _users schema. An unmarked member rejects the whole edit with 403 SELF_FIELD_REFUSED and identifies the field. A value rejected by the schema returns 400 SCHEMA_REFUSED. A key receives 403 because it is not a user. Email and password changes use separate verified flows. Returns the profile as auth.me does.

Route: PATCH /v1/_auth/me
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.me.update

Parameters

Name	In	Type	Required	Description
`name`	body	`string`	No	The person's display name.
`fields`	body	`object`	No	Members of the person object, each one the app's _users schema marks self.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_auth/me" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.mfa`

Finish a sign-in that answered mfa_required: trade its challenge and a code, or a recovery code, for the session. After the email code, remember true also remembers the device (the substrio_device cookie, 30 days).

Route: POST /v1/_auth/mfa
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.mfa

Parameters

Name	In	Type	Required	Description
`challenge`	body	`string`	Yes	From the sign-in that answered mfa_required.
`code`	body	`string`	No	The six digits of the authenticator app.
`recovery_code`	body	`string`	No	One of the recovery codes, instead of code; each works once.
`remember`	body	`boolean`	No	Remember this device (a sign-in that began with the email code only): its next sign-in asks for the authenticator code with no email. The answer sets the substrio_device cookie; false when absent.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/mfa" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"challenge":"challenge"}'

`auth.mfa.disable`

Turn MFA off with a code or a recovery code; every older session ends at its refresh.

Route: POST /v1/_auth/mfa/disable
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.mfa.disable

Parameters

Name	In	Type	Required	Description
`code`	body	`string`	No	The six digits of the authenticator app.
`recovery_code`	body	`string`	No	One of the recovery codes, instead of code.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/mfa/disable" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.mfa.recovery.regenerate`

Replace the recovery codes, with a code from the authenticator app; the old ones stop working.

Route: POST /v1/_auth/mfa/recovery_codes
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.mfa.recovery.regenerate

Parameters

Name	In	Type	Required	Description
`code`	body	`string`	No	The six digits of the authenticator app.
`recovery_code`	body	`string`	No	One of the recovery codes, instead of code.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/mfa/recovery_codes" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.mfa.totp.confirm`

Confirm the authenticator app with a code: MFA is on, the recovery codes are shown once, and every older session ends at its refresh.

Route: POST /v1/_auth/mfa/totp/confirm
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.mfa.totp.confirm

Parameters

Name	In	Type	Required	Description
`code`	body	`string`	Yes	The six digits of the authenticator app.
`challenge`	body	`string`	No	From a sign-in that answered mfa_enrollment_required, instead of a session.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/mfa/totp/confirm" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"code"}'

`auth.mfa.totp.start`

Start enrolling an authenticator app: returns its secret and otpauth URI; MFA is on once a code confirms it.

Route: POST /v1/_auth/mfa/totp
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.mfa.totp.start

Parameters

Name	In	Type	Required	Description
`challenge`	body	`string`	No	From a sign-in that answered mfa_enrollment_required, instead of a session.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/mfa/totp" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.oauth`

Authenticate with an OAuth provider.

Route: POST /v1/_auth/oauth
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.oauth

Parameters

Name	In	Type	Required	Description
`provider`	body	`string`	Yes	A provider of `auth.provider.catalog` (google, apple, microsoft, facebook, github, discord, linkedin, gitlab, slack, twitch, yahoo, salesforce, oidc), or meta, twitter or x.
`token`	body	`string`	No
`code`	body	`string`	No
`name`	body	`string`	No	Read only for apple.
`request`	body	`string`	No	At the identity app, the pending hosted sign-in that a button naming a client belongs to. The code was issued to that app's own registration, so the answer is redirect_to for that app, and no session opens.

Response

Field	Type	Present	Description
`success`	`any`	When set
`user_id`	`integer`	When set
`token`	`string`	When set
`provider`	`"google" \| "github" \| "facebook" \| "meta" \| "apple" \| "microsoft" \| "discord" \| "twitter" \| "x" \| "oidc"`	When set
`email`	`string`	When set
`name`	`string`	When set
`keyring`	`string`	When set	Matches `^0x[0-9a-fA-F]{16}$`.
`redirect_to`	`string`	When set	With request: where the hosted page sends the person, carrying that app's code. The answer then holds nothing else.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/oauth" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"provider"}'

`auth.passkey.delete`

Remove one of the signed-in person's passkeys; it signs in no more.

Route: DELETE /v1/_auth/passkeys/{id}
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.passkey.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The credential id, base64url.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_auth/passkeys/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.passkey.list`

List the signed-in person's passkeys.

Route: GET /v1/_auth/passkeys
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.passkey.list

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/passkeys" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.passkey.register`

Finish registering a passkey: verifies the attestation (none, or packed self-attestation) and stores the credential.

Route: POST /v1/_auth/passkeys/register
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.passkey.register

Parameters

Name	In	Type	Required	Description
`id`	body	`string`	No	The credential id, base64url.
`name`	body	`string`	No	What the person calls this passkey.
`response`	body	`object`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/passkeys/register" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"response":{"clientDataJSON":"clientDataJSON","attestationObject":"attestationObject"}}'

`auth.passkey.register.options`

Start registering a passkey: returns the WebAuthn creation options (challenge, rp, user handle, ES256 and RS256) for navigator.credentials.create.

Route: POST /v1/_auth/passkeys/register/options
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.passkey.register.options

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/passkeys/register/options" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.passkey.rename`

Rename one of the signed-in person's passkeys.

Route: PATCH /v1/_auth/passkeys/{id}
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.passkey.rename

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The credential id, base64url.
`name`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_auth/passkeys/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name"}'

`auth.passkey.sign_in`

Sign in with a passkey and no password: verifies the assertion and returns a session; a passkey that verified the person needs no 2FA.

Route: POST /v1/_auth/passkeys/sign-in
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.passkey.sign_in

Parameters

Name	In	Type	Required	Description
`id`	body	`string`	Yes	The credential id, base64url.
`response`	body	`object`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/passkeys/sign-in" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"id","response":{"clientDataJSON":"clientDataJSON","authenticatorData":"authenticatorData","signature":"signature"}}'

`auth.passkey.sign_in.options`

Start a passkey sign-in: returns the WebAuthn request options for navigator.credentials.get, for a discoverable passkey or a person's by email.

Route: POST /v1/_auth/passkeys/sign-in/options
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.passkey.sign_in.options

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	No	Offer this person's passkeys; without it, any discoverable passkey signs in.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/passkeys/sign-in/options" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.password.change`

Change the signed-in user's password; every other session ends.

Route: POST /v1/_auth/password
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.password.change

Parameters

Name	In	Type	Required	Description
`current_password`	body	`string`	Yes
`new_password`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/password" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"current_password","new_password":"new_password"}'

`auth.password.reset`

Set a new password with a reset token; every session ends.

Route: POST /v1/_auth/password/reset
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.password.reset

Parameters

Name	In	Type	Required	Description
`token`	body	`string`	Yes
`new_password`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/password/reset" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"token","new_password":"new_password"}'

`auth.password.reset_request`

Mail a password reset link, if the email belongs to a user.

Route: POST /v1/_auth/password/reset_request
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.password.reset_request

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	Yes
`turnstile_token`	body	`string`	No	On the platform host's identity app: the token of the Cloudflare Turnstile check the page showed (`auth.turnstile` names its site key); refused TURNSTILE_REQUIRED without one while the platform sets turnstile_secret.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/password/reset_request" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"email"}'

`auth.provider.catalog`

Every social sign-in provider the platform signs people in with: its label, protocol, the fields a registration of it takes, its default scopes, how it answers at the return address, where its client is registered and how long its secret lives.

Route: GET /v1/_auth/provider-catalog
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.provider.catalog

Parameters

No parameters.

Response

Field	Type	Present	Description
`providers`	`array of object`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/provider-catalog" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.provider.delete`

Remove one identity provider of the app by name.

Route: DELETE /v1/_auth/providers
DELETE /v1/_auth/providers/{provider}
Auth: App key tenant
MCP tool: substrio_auth_provider_delete
CLI: substrio op auth.provider.delete

Parameters

Name	In	Type	Required	Description
`provider`	path	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_auth/providers" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.provider.get`

Read one identity provider of the app by name.

Route: GET /v1/_auth/providers/{provider}
Auth: App key tenant
MCP tool: substrio_auth_provider_get
CLI: substrio op auth.provider.get

Parameters

Name	In	Type	Required	Description
`provider`	path	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/providers/$PROVIDER" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.provider.list`

List the app's identity providers (social sign-in).

Route: GET /v1/_auth/providers
Auth: App key tenant
MCP tool: substrio_auth_provider_list
CLI: substrio op auth.provider.list

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/providers" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.provider.update`

Configure one identity provider of the app for social sign-in; see the schema for its body.

Route: POST /v1/_auth/providers
Auth: App key tenant
MCP tool: substrio_auth_provider_update
CLI: substrio op auth.provider.update

Parameters

Name	In	Type	Required	Description
`provider`	body	`string`	Yes
`client_id`	body	`string`	No	Required unless enabled is false: an app turns a provider off with no registration of its own.
`client_secret`	body	`string`	No
`redirect_uri`	body	`string`	No
`scopes`	body	`string`	No
`provider_url`	body	`string`	No	The custom OIDC row: the issuer whose discovery document names the endpoints.
`authorize_url`	body	`string`	No	The custom OIDC row: the authorize endpoint the sign-in button opens.
`team_id`	body	`string`	No	Apple: the Team ID.
`key_id`	body	`string`	No	Apple: the Key ID of the Sign in with Apple key (client_secret).
`enabled`	body	`boolean`	No
`secret_expires_at`	body	`integer`	No	When the provider stops accepting client_secret, in Unix seconds (0: never). A new client_secret without it clears the date. Minimum 0.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/providers" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"provider"}'

`auth.refresh`

Refresh a session: the Bearer token for a new one (the old one stops working). stay true also sets the substrio_session cookie (30 days, renewed by each refresh); with no Bearer, that cookie alone signs its person in again as their sign-in did.

Route: POST /v1/_auth/refresh
POST /v1/auth/refresh
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.refresh

Parameters

Name	In	Type	Required	Description
`stay`	body	`boolean`	No	Stay signed in on this browser: the answer sets the substrio_session cookie (HttpOnly), which `auth.refresh` with no Bearer trades for a session for 30 days, each refresh renewing it; false when absent.

Response

Field	Type	Present	Description
`success`	`any`	Always
`token`	`string`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/refresh" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.register`

Create a user session.

Route: POST /v1/_auth/register
POST /v1/auth/signup
Auth: None none
CLI: substrio op auth.register

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	Yes
`password`	body	`string`	Yes

Response

Field	Type	Present
`success`	`any`	Always
`user_id`	`integer`	Always
`token`	`string`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"email","password":"password"}'

`auth.settings.get`

Read the app's auth settings: its email function and link URLs.

Route: GET /v1/_auth/settings
Auth: App key tenant
MCP tool: substrio_auth_settings_get
CLI: substrio op auth.settings.get

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/settings" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.settings.set`

Set the app's auth settings: its email function, link URLs and token lifetimes.

Route: PUT /v1/_auth/settings
Auth: App key tenant
MCP tool: substrio_auth_settings_set
CLI: substrio op auth.settings.set

Parameters

Name	In	Type	Required	Description
`email_function`	body	`string`	No
`reset_url`	body	`string`	No
`verify_url`	body	`string`	No
`invite_url`	body	`string`	No
`reset_token_seconds`	body	`integer`	No	Minimum 60.
`verify_token_seconds`	body	`integer`	No	Minimum 60.
`request_interval_seconds`	body	`integer`	No	Minimum 0.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PUT "$SUBSTRIO_URL/v1/_auth/settings" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.signin_providers`

The social sign-in buttons a sign-in page offers: each provider the app registered (at the identity app, its shared registrations) with its authorize URL; public client ids only, never a secret.

Route: GET /v1/_auth/signin-providers
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.signin_providers

Parameters

Name	In	Type	Required	Description
`client`	query	`string`	No	at the identity app, the client whose sign-in page this is: its own registrations replace the shared ones and the providers it turned off are left out.

Response

Field	Type	Present	Description
`providers`	`array of object`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/signin-providers" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.substrio`

Route: POST /v1/_auth/substrio
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.substrio

Parameters

Name	In	Type	Required
`code`	body	`string`	Yes
`redirect_uri`	body	`string`	Yes
`code_verifier`	body	`string`	Yes

Response

Field	Type	Present	Description
`success`	`any`	Always
`user_id`	`integer`	Always
`token`	`string`	Always
`keyring`	`string`	Always	Matches `^0x[0-9a-fA-F]{16}$`.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_auth/substrio" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"code","redirect_uri":"redirect_uri","code_verifier":"code_verifier"}'

`auth.turnstile`

The Cloudflare Turnstile site key the platform host's sign-in pages show, and the gate's state: {site_key, gate} where gate is on (a passed check before every code mail), closed (required with no secret set, so every code mail is refused) or off (the operator set turnstile_required false).

Route: GET /v1/_auth/turnstile
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.turnstile

Parameters

No parameters.

Response

Field	Type	Present	Description
`site_key`	`string`	Always	The widget's public key; empty when none is set.
`gate`	`"on" \| "closed" \| "off"`	Always	on: every code mail needs a passed check; closed: the check is required and no secret is set, so every code mail is refused; off: the operator turned it off.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_auth/turnstile" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`auth.whoami`

Which account and app a key belongs to, and its scopes.

Route: GET /v1/_whoami
GET /_whoami
Auth: App key or user session; your security rules apply none
CLI: substrio op auth.whoami

Parameters

No parameters.

Response

Field	Type	Present
`key`	`"system" \| "tenant" \| "account" \| "app_customer"`	Always
`account_id`	`integer`	Always
`tenant`	`string or null`	Always
`tenant_id`	`integer or null`	Always
`scopes`	`array of "system_admin" \| "account_admin" \| "tenant_admin" \| "app_customer" \| "test_mode"`	Always

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_whoami" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`oauth`

`oauth.authorize`

Start an authorization code request with PKCE and redirect to the consent page.

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.authorize

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.authorize

`oauth.consent_page`

Read the page a person approves or denies an authorization request on (text/html).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.consent_page

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.consent_page

`oauth.register`

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.register

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.register

`oauth.request.decide`

Approve or deny a pending authorization request as the signed-in person.

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.request.decide

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.request.decide

`oauth.request.get`

Read what a pending authorization request asks for.

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.request.get

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.request.get

`oauth.resource_metadata`

Read the OAuth protected resource metadata of the tenant or of one MCP endpoint (RFC 9728).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.resource_metadata

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.resource_metadata

`oauth.revoke`

Revoke an access or refresh token (RFC 7009, form-encoded).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.revoke

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.revoke

`oauth.server_metadata`

Read the tenant's OAuth authorization server metadata (RFC 8414).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.server_metadata

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.server_metadata

`oauth.token`

Exchange an authorization code or a refresh token for an access token (form-encoded).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oauth.token

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oauth.token

`oidc`

`oidc.authorize`

Start an OpenID Connect sign-in request and redirect to the sign-in page.

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oidc.authorize

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oidc.authorize

`oidc.discovery`

Read the OpenID Connect provider's discovery document.

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oidc.discovery

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oidc.discovery

`oidc.jwks`

Read the keys that verify the provider's ID tokens (JWKS).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oidc.jwks

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oidc.jwks

`oidc.request.decide`

Approve or deny a pending sign-in request as the signed-in person.

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oidc.request.decide

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oidc.request.decide

`oidc.request.get`

Read what a pending sign-in request asks for.

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oidc.request.get

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oidc.request.get

`oidc.signin_page`

Read the page a person signs in and consents on (text/html).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oidc.signin_page

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oidc.signin_page

`oidc.token`

Exchange an authorization code for an ID token and an access token (form-encoded).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oidc.token

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oidc.token

`oidc.userinfo`

Read the claims of the person an access token was issued for.

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op oidc.userinfo

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

substrio op oidc.userinfo

`permissions`

`permissions.get`

Read the tenant's declared permission catalog: each name, its bit and its closure (the names it implies, itself excluded), and the all name, if one closes to every bit, or null.

Route: GET /v1/_permissions
Auth: App key tenant
MCP tool: substrio_permissions_get
CLI: substrio op permissions.get

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_permissions" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`permissions.set`

Declare the tenant's permission catalog: body names, all, implies; append only against the stored names (a reorder or rename is refused, naming the position). A deploy without this table changes nothing. Answers the stored catalog.

Route: POST /v1/_permissions
Auth: App key tenant
MCP tool: substrio_permissions_set
CLI: substrio op permissions.set

Parameters

Name	In	Type	Required	Description
`names`	body	`array of string`	Yes	Each name's position is its bit; a later deploy may only append.
`all`	body	`string`	No	A declared name whose closure is every bit, the ones not declared yet included.
`implies`	body	`object`	No	declared name -> the declared names it implies.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_permissions" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names":[]}'

`rate_limit`

`rate_limit.delete`

Delete one rate-limit rule by its id, as rate_limit.list returned it: the limit stops applying at once and the rule cannot be restored, only added again with rate_limit.set. Answers 404 for an unknown id.

Route: DELETE /v1/_ratelimit/{id}
Auth: App key tenant
MCP tool: substrio_rate_limit_delete
CLI: substrio op rate_limit.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The rate-limit rule's id, as `rate_limit.list` or `rate_limit.set` returned it.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_ratelimit/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`rate_limit.list`

List the app's rate-limit rules, each with its id (the id rate_limit.delete takes), path, method, key mode, max_requests and window_seconds.

Route: GET /v1/_ratelimit
Auth: App key tenant
MCP tool: substrio_rate_limit_list
CLI: substrio op rate_limit.list

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_ratelimit" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`rate_limit.set`

Add a rate-limit rule: at most max_requests per window_seconds on the operations and the app's own function routes a path pattern and method name, counted per ip, token or tenant (by). Answers {id, success, matches: {operations, routes}}: what the pattern covers now (a pattern that covers nothing yet is accepted and limits a function route once it is deployed); a path that is neither * nor starts with / is 400, and a rule that is invalid or a duplicate of an existing one 409, so this adds and never updates one in place: delete the old rule by id first. Over a rule a request answers 429 with Retry-After; the master key is exempt.

Route: POST /v1/_ratelimit
Auth: App key tenant
MCP tool: substrio_rate_limit_set
CLI: substrio op rate_limit.set

Parameters

Name	In	Type	Required	Description
`path`	body	`string`	Yes	the path pattern the rule limits: * (every operation), a prefix ending in * (/v1/kv/) or one exact path; it is matched against the operation registry's routes and against the app's own function routes as declared (/api/:id, /hooks/), so a collection's name selects the route's operation for every collection. A pattern that matches nothing yet is accepted: it limits a function route once that route is deployed.
`method`	body	`string`	Yes	* or the HTTP method the rule limits.
`by`	body	`"ip" \| "token" \| "tenant"`	Yes	what a request is counted against: tenant (one count), ip (each client address) or token (each signed-in caller).
`max_requests`	body	`integer`	Yes	requests allowed per window. Minimum 1.
`window_seconds`	body	`integer`	Yes	the window length in seconds. Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_ratelimit" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"path","method":"method","by":"ip","max_requests":1,"window_seconds":1}'

`role`

`role.assign`

Assign a role to one end user: the route's {id} and the role in the body.

Route: POST /v1/_users/{id}/role
PUT /v1/_users/{id}/role
Auth: App key tenant
MCP tool: substrio_role_assign
CLI: substrio op role.assign

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The user's id, as `user.list` returned it.
`role`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_users/$ID/role" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"role"}'

`role.create`

Create a role: a name with the operations it grants and denies, optionally inheriting another role.

Route: POST /v1/_roles
POST /_roles
Auth: App key tenant
MCP tool: substrio_role_create
CLI: substrio op role.create

Parameters

Name	In	Type	Required
`name`	body	`string`	Yes
`description`	body	`string`	No
`inherits`	body	`string`	No
`grants`	body	`array of string`	No
`denies`	body	`array of string`	No

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_roles" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name"}'

`role.delete`

Delete one role by its name (the route's {name}); role.list shows the roles.

Route: DELETE /v1/_roles/{name}
DELETE /_roles/{name}
Auth: App key tenant
MCP tool: substrio_role_delete
CLI: substrio op role.delete

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The role's name, as `role.list` names it.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_roles/$NAME" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`role.list`

List the app's roles with what each grants and denies.

Route: GET /v1/_roles
GET /_roles
Auth: App key tenant
MCP tool: substrio_role_list
CLI: substrio op role.list

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_roles" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`role.update`

Change one role by name; see the schema for the fields.

Route: PATCH /v1/_roles/{name}
PUT /v1/_roles/{name}
PATCH /_roles/{name}
Auth: App key tenant
MCP tool: substrio_role_update
CLI: substrio op role.update

Parameters

Name	In	Type	Required	Description
`name`	path	`string`	Yes	The role's name, as `role.list` names it.
`description`	body	`string`	No
`inherits`	body	`string`	No
`grants`	body	`array of string`	No
`denies`	body	`array of string`	No

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_roles/$NAME" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user`

`user.count`

Count the app's end users; user.list pages through them.

Route: GET /v1/_users/_count
Auth: App key tenant
MCP tool: substrio_user_count
CLI: substrio op user.count

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer`	No	Minimum 1.
`skip`	query	`integer`	No	Minimum 0.
`cursor`	query	`string`	No	next_cursor of the page before: the walk starts past it (no skip steps).
`prefix`	query	`string`	No	only the people whose email starts with this, in any case.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_users/_count" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.create`

Create an end user: body email, and password (or password_hash from another system) for one who signs in; with neither, a person with no credential (a contact, a guest) who is still a full user. Optional name and fields (the person object's own members), role, keyring, verified flag and metadata. Answers 201 {user_id}.

Route: POST /v1/_users
Auth: App key tenant
MCP tool: substrio_user_create
CLI: substrio op user.create

Parameters

Name	In	Type	Required	Description
`email`	body	`string`	Yes
`password`	body	`string`	No
`password_hash`	body	`string or object`	No	Instead of password, a hash made elsewhere: a $argon2id$ or $pbkdf2-sha512$ (or $pbkdf2-sha256$) string, or {algorithm, iterations, salt, hash, salt_encoding (utf8\|hex\|base64, default utf8), hash_encoding (default hex), memory_kib and lanes for argon2id}. The first sign-in re-hashes it. bcrypt is refused (BCRYPT_UNSUPPORTED).
`keyring`	body	`integer or string`	No
`role`	body	`string`	No
`verified`	body	`boolean`	No
`metadata`	body	`object`	No
`name`	body	`string`	No	The person's display name, a member of the person object (collection _users).
`fields`	body	`object`	No	The person's own fields, written as members of the person object (_users, keyed by the user id) in the same insert: the standard ones (given_name, family_name, phone, picture, locale, timezone, birthday, consent, tags) and the ones the app declares in the _users schema. email, created_at, email_verified and a name starting with an underscore are reserved (400). A member the schema does not declare answers 400 SCHEMA_REFUSED with each violation and nothing is created.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_users" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"email"}'

`user.delete`

Mark one end user deleted by id; the hard option erases the user instead.

Route: DELETE /v1/_users/{id}
Auth: App key tenant
MCP tool: substrio_user_delete
CLI: substrio op user.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`hard`	query	`boolean`	No	true erases the user instead of marking them deleted.
`dry_run`	query	`boolean`	No	true checks whether deletion is allowed without erasing anything.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_users/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.email.change`

Change one end user's address (the route's {id}): body email. The sign-in and the person object (_users) move together, the new address unverified and every session of the person ended; the old address is free at once. 409 when another person (a contact too) holds it. Answers the user as user.get does.

Route: POST /v1/_users/{id}/email
Auth: App key tenant
MCP tool: substrio_user_email_change
CLI: substrio op user.email.change

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The user's id, as `user.list` returned it.
`email`	body	`string`	Yes	The person's new address: the account and the person object (_users) move together, the address unverified and every session of the person ended. 409 when another person holds it.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_users/$ID/email" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"email"}'

`user.get`

Read one end user by id (from user.list).

Route: GET /v1/_users/{id}
Auth: App key tenant
MCP tool: substrio_user_get
CLI: substrio op user.get

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

KEY_NOT_FOUND: call user.list to find the right one.

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_users/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.impersonate`

Impersonate one end user by id, to see the app as they do; admin only.

Route: POST /v1/_users/{id}/impersonate
Auth: App key tenant
MCP tool: substrio_user_impersonate
CLI: substrio op user.impersonate

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_users/$ID/impersonate" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.impersonate.exit`

End an impersonated session: answers a fresh ordinary token for the administrator who started it, their own full grants restored, no impersonation mark. Only an impersonated session may call this.

Route: POST /v1/_users/impersonate/exit
Auth: App key or user session; your security rules apply none
MCP tool: substrio_user_impersonate_exit
CLI: substrio op user.impersonate.exit

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_users/impersonate/exit" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.list`

List the app's end users in email order, a page at a time: limit, then cursor (the previous page's next_cursor) or skip; prefix keeps the emails that start with it. total is every person of the app.

Route: GET /v1/_users
Auth: App key tenant
MCP tool: substrio_user_list
CLI: substrio op user.list

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer (0 or more)`	No	the most items to return.
`skip`	query	`integer (0 or more)`	No	items to skip before the first one returned.
`cursor`	query	`string`	No	resume after the previous page: its next_cursor.
`prefix`	query	`string`	No	only the items whose key starts with this: a file's path, a person's email (absent lists every one).
`limit`	query	`integer`	No	Minimum 1.
`skip`	query	`integer`	No	Minimum 0.
`cursor`	query	`string`	No	next_cursor of the page before: the walk starts past it (no skip steps).
`prefix`	query	`string`	No	only the people whose email starts with this, in any case.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_users" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.memberships.get`

Read a user's membership: body user_id alone answers every organization held ({organization, names} rows, a range walk of the user's own key prefix); with collection and id, the one organization's held names.

Route: GET /v1/_memberships
Auth: App key tenant
MCP tool: substrio_user_memberships_get
CLI: substrio op user.memberships.get

Parameters

Name	In	Type	Required	Description
`user_id`	query	`integer`	Yes	Minimum 1.
`collection`	query	`string`	No
`id`	query	`string`	No

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_memberships" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.memberships.set`

Grant or revoke a user's membership in one organization (body user_id, collection, id) by permission name: body grant and revoke, either omitted, or body set alone, the exact names the membership holds after (an empty set ends it). The organization is the id as given, or derived through the collection's declared id.derive prefix. No session is ended; the gate reads the pair fresh on every request, so a revoke holds from the next one. Answers the names held in that organization.

Route: POST /v1/_memberships
Auth: App key tenant
MCP tool: substrio_user_memberships_set
CLI: substrio op user.memberships.set

Parameters

Name	In	Type	Required	Description
`user_id`	body	`integer`	Yes	Minimum 1.
`collection`	body	`string`	Yes
`id`	body	`string`	Yes
`grant`	body	`array of string`	No
`revoke`	body	`array of string`	No
`set`	body	`array of string`	No

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_memberships" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":1,"collection":"collection","id":"id"}'

`user.permission.check`

Ask whether one end user (the route's {id}) may run an operation on a collection: options collection and operation, both required.

Route: GET /v1/_users/{id}/can
Auth: App key tenant
MCP tool: substrio_user_permission_check
CLI: substrio op user.permission.check

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.
`collection`	query	`string`	No	the collection to check (required).
`operation`	query	`string`	No	the operation to check (required).
`collection`	query	`string`	Yes
`operation`	query	`"read" \| "write" \| "create" \| "delete" \| "list" \| "query" \| "admin"`	Yes

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_users/$ID/can" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.permissions.get`

Read one end user's (the route's {id}) declared permission catalog names: granted (its stored raw bits) and effective (granted, closed).

Route: GET /v1/_users/{id}/permissions
Auth: App key tenant
MCP tool: substrio_user_permissions_get
CLI: substrio op user.permissions.get

Parameters

Name	In	Type	Required	Description
`id`	path	`integer`	Yes	Minimum 1.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_users/$ID/permissions" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.permissions.set`

Grant or revoke one end user's (the route's {id}) declared permissions by name: body grant and revoke, either omitted. A revoke that actually removes a held bit ends the user's sessions; a grant takes effect at the next sign in. Answers the user's granted and effective names.

Route: POST /v1/_users/{id}/permissions
Auth: App key tenant
MCP tool: substrio_user_permissions_set
CLI: substrio op user.permissions.set

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The user's id, as `user.list` returned it.
`grant`	body	`array of string`	No
`revoke`	body	`array of string`	No

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_users/$ID/permissions" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`user.update`

Change one end user by id; see the schema for the fields.

Route: PATCH /v1/_users/{id}
Auth: App key tenant
MCP tool: substrio_user_update
CLI: substrio op user.update

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The user's id, as `user.list` returned it.
`keyring`	body	`integer or string`	No
`locked`	body	`boolean`	No
`disabled`	body	`boolean`	No
`email_verified`	body	`boolean`	No
`admin`	body	`boolean`	No
`password`	body	`string`	No
`role`	body	`string`	No
`metadata`	body	`object`	No
`name`	body	`string`	No	The person's display name, a member of the person object (collection _users).
`fields`	body	`object`	No	Members to set on the person object (_users) in one edit; members it does not name are kept. The reserved names and the schema refusal are those of `user.create`.

Response

A JSON object.

Errors

A failed call returns an error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_users/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"