torii-backend 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69a7cc52abd5b85f92c4d597f712da8c6f025de4aa486abf6a35bbd8fc136128
-  data.tar.gz: 8ace55761be96d67053626cacbd34cb5e823130bdd9f5e00499a13d6c048ec36
+  metadata.gz: 8ae4e717e56eba2a80cb484816d18969ae2d1d6632d5dbef7ad20d028317d7de
+  data.tar.gz: 3a223fa8c89c5b95fdea828ed1d7570a92aec485b122c87d620b44c44d90523b
 SHA512:
-  metadata.gz: 423343331cb1efb385dd06a91643fd65494996c5e20945c049f399ecf5aeea0dd718c47271956560866b17f9660fa706952f873c6f395f3693424f15d8cdaaad
-  data.tar.gz: 18e2ef7a673af34fbaf5776d39f8fa43de03589049ce5a111ed3cca831abf7bff1ce193d728de56499b96bc884238e1020baf87db9046a32d796c35d3bfe5ee4
+  metadata.gz: fcb8e4f580d3232851913d0b2dea502d0f4ee00d37e76382f2770ba307aefcc723422fa8f967c34a4b062bceb6309d1f71e4f2504b6e8a1a03965871bcdbdcfd
+  data.tar.gz: b8b404a9f7d7729524ade57530fec70b407b334824b10ed5ab2a5f7b58efd8b555ab117ecd329e14f85245c90eae39b1ffbe0684ad66f167ec4d4425ca1486e9

data/spec/server-v1.json

@@ -1 +1 @@
-{"openapi":"3.1.0","info":{"title":"Torii Backend API","description":"Server-to-server API (BAPI) for backend SDKs. Authenticated with a secret key (Bearer sk_live_* / sk_test_*).","version":"v1"},"servers":[{"url":"https://api.torii.so","description":"Production backend API"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Allowed Origins","description":"Escape-hatch origins for non-web stacks (secret key auth)"},{"name":"Server Impersonation","description":"Secret-key impersonation token minting"},{"name":"Invitations","description":"Invite end-users into the environment (secret key auth)"},{"name":"Server Users","description":"Server user management endpoints (secret key auth)"},{"name":"Server Sessions","description":"Server session management endpoints (secret key auth)"}],"paths":{"/api/server/v1/allowed-origins":{"get":{"tags":["Allowed Origins"],"summary":"List escape-hatch origins for this environment","operationId":"list","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOriginsResponse"}}}}}},"put":{"tags":["Allowed Origins"],"summary":"Replace the escape-hatch origins for this environment","description":"Full origins incl. non-http schemes (e.g. capacitor://localhost). Replaces the list.","operationId":"set","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetAllowedOriginsRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOriginsResponse"}}}}}}},"/api/server/v1/users":{"post":{"tags":["Server Users"],"summary":"Create user","description":"Creates an end-user in your environment. All body fields are optional; supply at minimum an email if you want the user to be able to sign in via email + password.","operationId":"createUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}},"required":true},"responses":{"201":{"description":"The created user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"400":{"description":"Invalid body (e.g. weak password, malformed email).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Another user with this email already exists in the environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/unban":{"post":{"tags":["Server Users"],"summary":"Unban user","description":"Reverses a previous ban. The user can sign in again on next request.","operationId":"unbanUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to unban.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The (now active) user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/impersonation-token":{"post":{"tags":["Server Impersonation"],"summary":"Mint an impersonation token","description":"Creates a single-use, short-lived impersonation token for the target user, attributed to `actorUserId`. Redeem it via `POST /_torii/auth/session/impersonate` to obtain a session and access token as the target user. Counts against the same per-period impersonation quota and usage ledger as the dashboard.","operationId":"mintImpersonationToken","parameters":[{"name":"userId","in":"path","description":"The user to impersonate.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerImpersonationTokenRequest"}}},"required":true},"responses":{"200":{"description":"The minted token and its lifetime.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerImpersonationTokenResponse"}}}},"400":{"description":"Deleted target, or `expiresInSeconds` out of the 60..600 range.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"402":{"description":"Plan does not include impersonation, or the per-period quota is exhausted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Target or actor is in another environment, or impersonation is disabled for this environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/ban":{"post":{"tags":["Server Users"],"summary":"Ban user","description":"Marks the user as banned and revokes all their active sessions.","operationId":"banUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to ban.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The (now banned) user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/search":{"post":{"tags":["Server Users"],"summary":"Search users","description":"Returns a cursor-paginated page of end-users in the environment matching the optional filters. Uses POST so the filter body can be sent without URL-encoding. Three id-selectors resolve users to a set of ids (`userIds`, the explicit batch-by-id lookup; `emailAddresses`, exact and case-insensitive; `email`, a case-insensitive substring); when more than one is supplied they are combined with AND (intersection). The remaining filters (`name`, `statuses`, `createdAfter`/`createdBefore`) apply on top.","operationId":"searchUsers","parameters":[{"name":"limit","in":"query","description":"Maximum number of items in the returned page (default 20).","required":false,"schema":{"type":"integer","format":"int32","default":20},"example":50},{"name":"cursor","in":"query","description":"Opaque cursor returned by the previous page's `nextCursor`. Omit to fetch the first page.","required":false,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserSearchRequest"}}}},"responses":{"200":{"description":"Page of matching users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPageResponseServerUserResponse"}}}},"400":{"description":"An id-selector list exceeds 100 entries.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/invitations":{"get":{"tags":["Invitations"],"summary":"List invitations for this environment","operationId":"list_1","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPageResponseEnvironmentInvitationResponse"}}}}}},"post":{"tags":["Invitations"],"summary":"Create an invitation with optional pre-seeded metadata","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnvironmentInvitationServerRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentInvitationResponse"}}}}}}},"/api/server/v1/invitations/{invitationId}/resend":{"post":{"tags":["Invitations"],"summary":"Resend a pending invitation with a fresh link","operationId":"resend","parameters":[{"name":"invitationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentInvitationResponse"}}}}}}},"/api/server/v1/users/{userId}":{"get":{"tags":["Server Users"],"summary":"Get user","description":"Returns the full profile for one end-user.","operationId":"getUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to fetch.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Server Users"],"summary":"Delete user","description":"Soft-deletes the user. Not idempotent at the HTTP layer: the authorization grant for the user is revoked on the first successful delete, so a subsequent DELETE for the same id returns 403 rather than 204. Treat 403 from a retry as a confirmation that the user is already deleted.","operationId":"deleteUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to delete.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"204":{"description":"User deleted."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"patch":{"tags":["Server Users"],"summary":"Update user","description":"Partial update with tri-state PATCH semantics. Every field in `UpdateUserRequest` is tri-state: omit the key to leave the field unchanged, send a non-null value to set it, or send JSON null to clear it.","operationId":"updateUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to update.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRequest"}}},"required":true},"responses":{"200":{"description":"The updated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"400":{"description":"Invalid body.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/metadata":{"patch":{"tags":["Server Users"],"summary":"Update user metadata","description":"Deep-merges into any of the three metadata bags. Each bag is tri-state: omit the key to leave the bag unchanged, or send an object to deep-merge into the existing bag (a key set to null removes it). The merged metadata is capped at 8 KB total across `publicMetadata`, `privateMetadata`, and `unsafeMetadata` combined (no per-bag limit).","operationId":"updateUserMetadata","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to update.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserMetadataRequest"}}},"required":true},"responses":{"200":{"description":"The updated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"400":{"description":"A bag exceeds its size limit.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/sessions":{"get":{"tags":["Server Sessions"],"summary":"List user sessions","description":"Returns all active (unexpired, unrevoked) sessions for the user, ordered by most recently used.","operationId":"listSessions","parameters":[{"name":"userId","in":"path","description":"Identifier of the user whose sessions to list.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"All active sessions for the user.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserSessionResponse"}}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Server Sessions"],"summary":"Revoke all sessions","description":"Immediately revokes every active session for the user. Idempotent.","operationId":"revokeAllSessions","parameters":[{"name":"userId","in":"path","description":"Identifier of the user whose sessions to revoke.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"204":{"description":"Sessions revoked."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/invitations/{invitationId}":{"get":{"tags":["Invitations"],"summary":"Get an invitation by id","operationId":"get","parameters":[{"name":"invitationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentInvitationResponse"}}}}}},"delete":{"tags":["Invitations"],"summary":"Revoke a pending invitation","operationId":"revoke","parameters":[{"name":"invitationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/api/server/v1/users/{userId}/sessions/{sessionId}":{"delete":{"tags":["Server Sessions"],"summary":"Revoke specific session","description":"Revokes a single session by id. Idempotent: returns 204 even if the session was already revoked or expired.","operationId":"revokeSession","parameters":[{"name":"userId","in":"path","description":"Identifier of the user who owns the session.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"},{"name":"sessionId","in":"path","description":"Identifier of the session to revoke.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a74-1234-7000-8000-000000000000"}],"responses":{"204":{"description":"Session revoked."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User or session belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}},"components":{"schemas":{"SetAllowedOriginsRequest":{"type":"object","properties":{"origins":{"type":"array","items":{"type":"string"}}},"required":["origins"]},"AllowedOriginsResponse":{"type":"object","properties":{"origins":{"type":"array","items":{"type":"string"}}},"required":["origins"]},"CreateUserRequest":{"type":"object","description":"Request body for creating an end-user in your environment. All fields are optional; supply at minimum an email if you want the user to be able to sign in via email + password.","properties":{"email":{"type":["string","null"],"description":"Primary email for the new user. If omitted, the user is created without a sign-in identity.","example":"ada@example.com"},"password":{"type":["string","null"],"description":"Initial password. Subject to the environment's password policy. Omit to create a passwordless user (e.g. social-only).","example":"correct horse battery staple"},"firstName":{"type":["string","null"],"description":"First (given) name to seed on the profile.","example":"Ada"},"lastName":{"type":["string","null"],"description":"Last (family) name to seed on the profile.","example":"Lovelace"},"publicMetadata":{"type":"object","additionalProperties":true,"description":"Initial public metadata (SDK-readable, server-written). Part of the 8 KB combined metadata budget.","example":{"plan":"free"}},"privateMetadata":{"type":"object","additionalProperties":true,"description":"Initial private metadata (server-only). Part of the 8 KB combined metadata budget.","example":{"billingCustomerId":"cus_123"}},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Initial unsafe metadata (end-user writable). Part of the 8 KB combined metadata budget.","example":{"onboardingStep":0}}}},"ProblemDetail":{"type":"object","properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer","format":"int32"},"detail":{"type":"string"},"instance":{"type":"string","format":"uri"},"properties":{"type":"object","additionalProperties":{}}}},"ServerUserResponse":{"type":"object","description":"An end-user, including server-only private metadata. Returned only on the secret-key backend API.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this user.","example":"01931a73-8b00-7000-8000-000000000000"},"environmentId":{"type":"string","format":"uuid","description":"Identifier of the environment this user belongs to.","example":"01931a72-0000-7000-8000-000000000000"},"name":{"type":["string","null"],"description":"Full name on the profile, if any.","example":"Ada Lovelace"},"firstName":{"type":["string","null"],"description":"First (given) name on the profile, if any.","example":"Ada"},"lastName":{"type":["string","null"],"description":"Last (family) name on the profile, if any.","example":"Lovelace"},"locale":{"type":["string","null"],"description":"Preferred locale for emails and UI messages.","enum":["en","da"]},"status":{"type":"string","description":"Lifecycle status of the user (e.g. active, banned).","enum":["active","banned","deleted"]},"createdAt":{"type":"string","format":"date-time","description":"When this user was created (ISO-8601 UTC).","example":"2026-05-16T09:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"When this user was last modified (ISO-8601 UTC).","example":"2026-05-16T10:00:00Z"},"email":{"type":["string","null"],"description":"Primary email on the profile, if any.","example":"ada@example.com"},"emailVerifiedAt":{"type":["string","null"],"format":"date-time","description":"When this user's primary email was verified, if it has been verified.","example":"2026-05-16T09:35:00Z"},"deletedAt":{"type":["string","null"],"format":"date-time","description":"When this user was deleted, if soft-deleted. Null for active users.","example":"2026-05-20T12:00:00Z"},"publicMetadata":{"type":"object","additionalProperties":true,"description":"Public metadata: readable by the SDK, writable only server-side.","example":{"plan":"pro"}},"privateMetadata":{"type":"object","additionalProperties":true,"description":"Private metadata: server-only. Never exposed to the SDK or in a JWT.","example":{"billingCustomerId":"cus_123"}},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Unsafe metadata: readable and writable by the end-user via the SDK.","example":{"onboardingStep":2}}},"required":["createdAt","environmentId","id","privateMetadata","publicMetadata","status","unsafeMetadata","updatedAt"]},"ServerImpersonationTokenRequest":{"type":"object","description":"Body for minting an impersonation token.","properties":{"actorUserId":{"type":"string","format":"uuid","description":"The principal the impersonation is on behalf of (recorded for accountability). Must be a user in this environment.","example":"01931a73-8b00-7000-8000-000000000000"},"reason":{"type":"string","description":"Mandatory justification (GDPR purpose limitation); recorded in the audit log on mint and redeem.","example":"Investigating support ticket #4821","maxLength":500,"minLength":0},"expiresInSeconds":{"type":["integer","null"],"format":"int64","description":"Optional token lifetime in seconds, 60..600. Omit for the 60s default.","example":120,"maximum":600,"minimum":60}},"required":["actorUserId","reason"]},"ServerImpersonationTokenResponse":{"type":"object","description":"A minted impersonation token.","properties":{"token":{"type":"string","description":"The single-use token. Redeem via POST /_torii/auth/session/impersonate."},"expiresInSeconds":{"type":"integer","format":"int64","description":"The token's lifetime in seconds (the resolved value after any override).","example":60}},"required":["expiresInSeconds","token"]},"ServerUserSearchRequest":{"type":"object","description":"Optional filter body for `POST /users/search`. Every field is tri-state: omit to skip that filter, send a value to apply it. The three id-selectors (`userIds`, `emailAddresses`, `email`) resolve users to a set of ids and, when more than one is supplied, are combined with AND (intersection); a supplied id-selector whose resolved set is empty returns an empty page. `name` additionally accepts JSON null to match users with no name; an explicit null or blank `email` contributes no restriction; the non-nullable `statuses` field rejects null.","properties":{"name":{"type":["string","null"],"description":"Filter by name (case-insensitive substring match). Send null to require users with no name.","example":"Ada"},"userIds":{"type":"array","description":"Restrict to these user ids (the explicit batch-by-id lookup), at most 100. AND-combined with the other id-selectors; an empty list returns an empty page.","example":["01931a73-8b00-7000-8000-000000000000"],"items":{"type":"string","format":"uuid"}},"emailAddresses":{"type":"array","description":"Resolve users by exact (case-insensitive) email address (one or more, at most 100). Unlike `email`, never matches a superstring. AND-combined with the other id-selectors; an empty list, or addresses matching nobody, returns an empty page.","example":["ada@example.com"],"items":{"type":"string"}},"email":{"type":["string","null"],"description":"Filter by primary email (case-insensitive substring match). AND-combined with the other id-selectors. An explicit null or blank value contributes no restriction.","example":"@example.com"},"statuses":{"type":"array","description":"Filter by user status. Returns users matching any of the supplied statuses.","items":{"type":"string","enum":["active","banned","deleted"]},"uniqueItems":true},"createdAfter":{"type":["string","null"],"format":"date-time","description":"Only return users created at or after this instant (ISO-8601 UTC).","example":"2026-01-01T00:00:00Z"},"createdBefore":{"type":["string","null"],"format":"date-time","description":"Only return users created at or before this instant (ISO-8601 UTC).","example":"2026-12-31T23:59:59Z"}}},"CursorPageResponseServerUserResponse":{"type":"object","description":"A single page of results in a cursor-paginated list. Pass `nextCursor` as the `cursor` query parameter to fetch the following page.","properties":{"items":{"type":"array","description":"Items in this page, in stable order.","items":{"$ref":"#/components/schemas/ServerUserResponse"}},"nextCursor":{"type":["string","null"],"format":"uuid","description":"Cursor to pass to fetch the next page. Null when this is the last page.","example":"01931a73-8b00-7000-8000-000000000000"},"hasMore":{"type":"boolean","description":"True if more pages are available (equivalent to `nextCursor != null`).","example":true}},"required":["hasMore","items"]},"CreateEnvironmentInvitationServerRequest":{"type":"object","properties":{"email":{"type":"string"},"expiresInDays":{"type":["integer","null"],"format":"int32"},"redirectUrl":{"type":["string","null"]},"publicMetadata":{"type":"object","additionalProperties":true},"privateMetadata":{"type":"object","additionalProperties":true}},"required":["email","privateMetadata","publicMetadata"]},"EnvironmentInvitationResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"email":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","REVOKED","EXPIRED"]},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"}},"required":["createdAt","email","environmentId","expiresAt","id","status"]},"UpdateUserRequest":{"type":"object","description":"PATCH body for updating an end-user. Every field is tri-state: omit the key entirely to leave the field unchanged, send a non-null value to set it, or send JSON null to clear it.","properties":{"firstName":{"type":["string","null"],"description":"New first (given) name. Send null to clear; omit to leave unchanged.","example":"Ada"},"lastName":{"type":["string","null"],"description":"New last (family) name. Send null to clear; omit to leave unchanged.","example":"Lovelace"},"locale":{"type":["string","null"],"description":"New preferred locale. Send null to clear; omit to leave unchanged.","enum":["en","da"]},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Deep-merges into the user's unsafe metadata (a key set to null removes it); omit to leave unchanged. Counts toward the 8 KB combined metadata budget.","example":{"onboardingStep":2}}}},"UpdateUserMetadataRequest":{"type":"object","description":"PATCH body for a user's metadata bags. Each bag is tri-state: omit to leave it unchanged, or send an object value. Whether the object merges into or replaces the bag depends on the endpoint (see its operation description).","properties":{"publicMetadata":{"type":"object","additionalProperties":true,"description":"Public metadata bag: SDK-readable, server-written. Part of the 8 KB combined metadata budget.","example":{"plan":"pro"}},"privateMetadata":{"type":"object","additionalProperties":true,"description":"Private metadata bag: server-only, never exposed to the SDK or in a JWT. Part of the 8 KB combined metadata budget.","example":{"billingCustomerId":"cus_123"}},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Unsafe metadata bag: readable and writable by the end-user via the SDK. Part of the 8 KB combined metadata budget.","example":{"onboardingStep":2}}}},"UserSessionResponse":{"type":"object","description":"An active end-user session in your environment.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this session.","example":"01931a74-1234-7000-8000-000000000000"},"userId":{"type":"string","format":"uuid","description":"Identifier of the end-user this session belongs to.","example":"01931a73-8b00-7000-8000-000000000000"},"environmentId":{"type":"string","format":"uuid","description":"Identifier of the environment this session belongs to.","example":"01931a72-0000-7000-8000-000000000000"},"userAgent":{"type":["string","null"],"description":"Raw User-Agent string captured when the session was created.","example":"Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6_0) AppleWebKit/537.36"},"ipAddress":{"type":["string","null"],"description":"IP address captured when the session was created.","example":"203.0.113.42"},"createdAt":{"type":"string","format":"date-time","description":"When this session was created (ISO-8601 UTC).","example":"2026-05-16T09:30:00Z"},"expiresAt":{"type":"string","format":"date-time","description":"When this session expires (ISO-8601 UTC).","example":"2026-05-23T09:30:00Z"},"lastUsedAt":{"type":"string","format":"date-time","description":"When this session was last seen by the API (ISO-8601 UTC).","example":"2026-05-16T11:42:00Z"},"activeOrganizationId":{"type":["string","null"],"format":"uuid","description":"Active organization pinned to this session (`org_id` claim on re-mint)."},"impersonatedBy":{"type":["string","null"],"format":"uuid","description":"Platform user behind this session when it was established via impersonation; null for normal sign-ins."}},"required":["createdAt","environmentId","expiresAt","id","lastUsedAt","userId"]},"CursorPageResponseEnvironmentInvitationResponse":{"type":"object","description":"A single page of results in a cursor-paginated list. Pass `nextCursor` as the `cursor` query parameter to fetch the following page.","properties":{"items":{"type":"array","description":"Items in this page, in stable order.","items":{"$ref":"#/components/schemas/EnvironmentInvitationResponse"}},"nextCursor":{"type":["string","null"],"format":"uuid","description":"Cursor to pass to fetch the next page. Null when this is the last page.","example":"01931a73-8b00-7000-8000-000000000000"},"hasMore":{"type":"boolean","description":"True if more pages are available (equivalent to `nextCursor != null`).","example":true}},"required":["hasMore","items"]}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Backend secret key (`sk_live_*` / `sk_test_*`) sent as `Authorization: Bearer <key>`.","scheme":"bearer"}}}}
+{"openapi":"3.1.0","info":{"title":"Torii Backend API","description":"Server-to-server API (BAPI) for backend SDKs. Authenticated with a secret key (Bearer sk_live_* / sk_test_*).","version":"v1"},"servers":[{"url":"https://api.torii.so","description":"Production backend API"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Allowed Origins","description":"Escape-hatch origins for non-web stacks (secret key auth)"},{"name":"Server Impersonation","description":"Secret-key impersonation token minting"},{"name":"Invitations","description":"Invite end-users into the environment (secret key auth)"},{"name":"Server Users","description":"Server user management endpoints (secret key auth)"},{"name":"Server Sessions","description":"Server session management endpoints (secret key auth)"}],"paths":{"/api/server/v1/allowed-origins":{"get":{"tags":["Allowed Origins"],"summary":"List escape-hatch origins for this environment","operationId":"list","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOriginsResponse"}}}}}},"put":{"tags":["Allowed Origins"],"summary":"Replace the escape-hatch origins for this environment","description":"Full origins incl. non-http schemes (e.g. capacitor://localhost). Replaces the list.","operationId":"set","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetAllowedOriginsRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOriginsResponse"}}}}}}},"/api/server/v1/users":{"post":{"tags":["Server Users"],"summary":"Create user","description":"Creates an end-user in your environment. All body fields are optional; supply at minimum an email if you want the user to be able to sign in via email + password.","operationId":"createUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}},"required":true},"responses":{"201":{"description":"The created user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"400":{"description":"Invalid body (e.g. weak password, malformed email).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Another user with this email already exists in the environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/unban":{"post":{"tags":["Server Users"],"summary":"Unban user","description":"Reverses a previous ban. The user can sign in again on next request.","operationId":"unbanUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to unban.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The (now active) user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/impersonation-token":{"post":{"tags":["Server Impersonation"],"summary":"Mint an impersonation token","description":"Creates a single-use, short-lived impersonation token for the target user, attributed to `actorUserId`. Redeem it programmatically via `POST /_torii/auth/session/impersonate` (access token in the body), or hand the returned `url` to an operator to open in a browser (establishes the session and redirects to the landing URL). Counts against the same per-period impersonation quota and usage ledger as the dashboard.","operationId":"mintImpersonationToken","parameters":[{"name":"userId","in":"path","description":"The user to impersonate.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerImpersonationTokenRequest"}}},"required":true},"responses":{"200":{"description":"The minted token, its lifetime, and (when a landing URL resolves) a ready-to-use redeem URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerImpersonationTokenResponse"}}}},"400":{"description":"Deleted target, `expiresInSeconds` out of the 60..600 range, or `redirectUrl` missing/malformed/not in the environment's allowed origins.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"402":{"description":"Plan does not include impersonation, or the per-period quota is exhausted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"Target or actor is in another environment, or impersonation is disabled for this environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/ban":{"post":{"tags":["Server Users"],"summary":"Ban user","description":"Marks the user as banned and revokes all their active sessions.","operationId":"banUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to ban.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The (now banned) user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/search":{"post":{"tags":["Server Users"],"summary":"Search users","description":"Returns a cursor-paginated page of end-users in the environment matching the optional filters. Uses POST so the filter body can be sent without URL-encoding. Three id-selectors resolve users to a set of ids (`userIds`, the explicit batch-by-id lookup; `emailAddresses`, exact and case-insensitive; `email`, a case-insensitive substring); when more than one is supplied they are combined with AND (intersection). The remaining filters (`name`, `statuses`, `createdAfter`/`createdBefore`) apply on top.","operationId":"searchUsers","parameters":[{"name":"limit","in":"query","description":"Maximum number of items in the returned page (default 20).","required":false,"schema":{"type":"integer","format":"int32","default":20},"example":50},{"name":"cursor","in":"query","description":"Opaque cursor returned by the previous page's `nextCursor`. Omit to fetch the first page.","required":false,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserSearchRequest"}}}},"responses":{"200":{"description":"Page of matching users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPageResponseServerUserResponse"}}}},"400":{"description":"An id-selector list exceeds 100 entries.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/invitations":{"get":{"tags":["Invitations"],"summary":"List invitations for this environment","operationId":"list_1","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPageResponseEnvironmentInvitationResponse"}}}}}},"post":{"tags":["Invitations"],"summary":"Create an invitation with optional pre-seeded metadata","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnvironmentInvitationServerRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentInvitationResponse"}}}}}}},"/api/server/v1/invitations/{invitationId}/resend":{"post":{"tags":["Invitations"],"summary":"Resend a pending invitation with a fresh link","operationId":"resend","parameters":[{"name":"invitationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentInvitationResponse"}}}}}}},"/api/server/v1/users/{userId}":{"get":{"tags":["Server Users"],"summary":"Get user","description":"Returns the full profile for one end-user.","operationId":"getUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to fetch.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"The user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Server Users"],"summary":"Delete user","description":"Soft-deletes the user. Not idempotent at the HTTP layer: the authorization grant for the user is revoked on the first successful delete, so a subsequent DELETE for the same id returns 403 rather than 204. Treat 403 from a retry as a confirmation that the user is already deleted.","operationId":"deleteUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to delete.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"204":{"description":"User deleted."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"patch":{"tags":["Server Users"],"summary":"Update user","description":"Partial update with tri-state PATCH semantics. Every field in `UpdateUserRequest` is tri-state: omit the key to leave the field unchanged, send a non-null value to set it, or send JSON null to clear it.","operationId":"updateUser","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to update.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRequest"}}},"required":true},"responses":{"200":{"description":"The updated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"400":{"description":"Invalid body.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/metadata":{"patch":{"tags":["Server Users"],"summary":"Update user metadata","description":"Deep-merges into any of the three metadata bags. Each bag is tri-state: omit the key to leave the bag unchanged, or send an object to deep-merge into the existing bag (a key set to null removes it). The merged metadata is capped at 8 KB total across `publicMetadata`, `privateMetadata`, and `unsafeMetadata` combined (no per-bag limit).","operationId":"updateUserMetadata","parameters":[{"name":"userId","in":"path","description":"Identifier of the user to update.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserMetadataRequest"}}},"required":true},"responses":{"200":{"description":"The updated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerUserResponse"}}}},"400":{"description":"A bag exceeds its size limit.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"No user with this id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/users/{userId}/sessions":{"get":{"tags":["Server Sessions"],"summary":"List user sessions","description":"Returns all active (unexpired, unrevoked) sessions for the user, ordered by most recently used.","operationId":"listSessions","parameters":[{"name":"userId","in":"path","description":"Identifier of the user whose sessions to list.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"200":{"description":"All active sessions for the user.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserSessionResponse"}}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Server Sessions"],"summary":"Revoke all sessions","description":"Immediately revokes every active session for the user. Idempotent.","operationId":"revokeAllSessions","parameters":[{"name":"userId","in":"path","description":"Identifier of the user whose sessions to revoke.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"}],"responses":{"204":{"description":"Sessions revoked."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/api/server/v1/invitations/{invitationId}":{"get":{"tags":["Invitations"],"summary":"Get an invitation by id","operationId":"get","parameters":[{"name":"invitationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentInvitationResponse"}}}}}},"delete":{"tags":["Invitations"],"summary":"Revoke a pending invitation","operationId":"revoke","parameters":[{"name":"invitationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/api/server/v1/users/{userId}/sessions/{sessionId}":{"delete":{"tags":["Server Sessions"],"summary":"Revoke specific session","description":"Revokes a single session by id. Idempotent: returns 204 even if the session was already revoked or expired.","operationId":"revokeSession","parameters":[{"name":"userId","in":"path","description":"Identifier of the user who owns the session.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a73-8b00-7000-8000-000000000000"},{"name":"sessionId","in":"path","description":"Identifier of the session to revoke.","required":true,"schema":{"type":"string","format":"uuid"},"example":"01931a74-1234-7000-8000-000000000000"}],"responses":{"204":{"description":"Session revoked."},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"description":"User or session belongs to a different environment.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}},"components":{"schemas":{"SetAllowedOriginsRequest":{"type":"object","properties":{"origins":{"type":"array","items":{"type":"string"}}},"required":["origins"]},"AllowedOriginsResponse":{"type":"object","properties":{"origins":{"type":"array","items":{"type":"string"}}},"required":["origins"]},"CreateUserRequest":{"type":"object","description":"Request body for creating an end-user in your environment. All fields are optional; supply at minimum an email if you want the user to be able to sign in via email + password.","properties":{"email":{"type":["string","null"],"description":"Primary email for the new user. If omitted, the user is created without a sign-in identity.","example":"ada@example.com"},"password":{"type":["string","null"],"description":"Initial password. Subject to the environment's password policy. Omit to create a passwordless user (e.g. social-only).","example":"correct horse battery staple"},"firstName":{"type":["string","null"],"description":"First (given) name to seed on the profile.","example":"Ada"},"lastName":{"type":["string","null"],"description":"Last (family) name to seed on the profile.","example":"Lovelace"},"publicMetadata":{"type":"object","additionalProperties":true,"description":"Initial public metadata (SDK-readable, server-written). Part of the 8 KB combined metadata budget.","example":{"plan":"free"}},"privateMetadata":{"type":"object","additionalProperties":true,"description":"Initial private metadata (server-only). Part of the 8 KB combined metadata budget.","example":{"billingCustomerId":"cus_123"}},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Initial unsafe metadata (end-user writable). Part of the 8 KB combined metadata budget.","example":{"onboardingStep":0}}}},"ProblemDetail":{"type":"object","properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer","format":"int32"},"detail":{"type":"string"},"instance":{"type":"string","format":"uri"},"properties":{"type":"object","additionalProperties":{}}}},"ServerUserResponse":{"type":"object","description":"An end-user, including server-only private metadata. Returned only on the secret-key backend API.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this user.","example":"01931a73-8b00-7000-8000-000000000000"},"environmentId":{"type":"string","format":"uuid","description":"Identifier of the environment this user belongs to.","example":"01931a72-0000-7000-8000-000000000000"},"name":{"type":["string","null"],"description":"Full name on the profile, if any.","example":"Ada Lovelace"},"firstName":{"type":["string","null"],"description":"First (given) name on the profile, if any.","example":"Ada"},"lastName":{"type":["string","null"],"description":"Last (family) name on the profile, if any.","example":"Lovelace"},"locale":{"type":["string","null"],"description":"Preferred locale for emails and UI messages.","enum":["en","da"]},"status":{"type":"string","description":"Lifecycle status of the user (e.g. active, banned).","enum":["active","banned","deleted"]},"createdAt":{"type":"string","format":"date-time","description":"When this user was created (ISO-8601 UTC).","example":"2026-05-16T09:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"When this user was last modified (ISO-8601 UTC).","example":"2026-05-16T10:00:00Z"},"email":{"type":["string","null"],"description":"Primary email on the profile, if any.","example":"ada@example.com"},"emailVerifiedAt":{"type":["string","null"],"format":"date-time","description":"When this user's primary email was verified, if it has been verified.","example":"2026-05-16T09:35:00Z"},"deletedAt":{"type":["string","null"],"format":"date-time","description":"When this user was deleted, if soft-deleted. Null for active users.","example":"2026-05-20T12:00:00Z"},"publicMetadata":{"type":"object","additionalProperties":true,"description":"Public metadata: readable by the SDK, writable only server-side.","example":{"plan":"pro"}},"privateMetadata":{"type":"object","additionalProperties":true,"description":"Private metadata: server-only. Never exposed to the SDK or in a JWT.","example":{"billingCustomerId":"cus_123"}},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Unsafe metadata: readable and writable by the end-user via the SDK.","example":{"onboardingStep":2}}},"required":["createdAt","environmentId","id","privateMetadata","publicMetadata","status","unsafeMetadata","updatedAt"]},"ServerImpersonationTokenRequest":{"type":"object","description":"Body for minting an impersonation token.","properties":{"actorUserId":{"type":"string","format":"uuid","description":"The principal the impersonation is on behalf of (recorded for accountability). Must be a user in this environment.","example":"01931a73-8b00-7000-8000-000000000000"},"reason":{"type":"string","description":"Mandatory justification (GDPR purpose limitation); recorded in the audit log on mint and redeem.","example":"Investigating support ticket #4821","maxLength":500,"minLength":0},"redirectUrl":{"type":["string","null"],"description":"Optional post-redeem landing URL for the `url` redeem link; its origin must be in the environment's allowed origins. Omit to default to the environment's first non-wildcard allowed origin.","example":"https://app.example.com/dashboard"},"expiresInSeconds":{"type":["integer","null"],"format":"int64","description":"Optional token lifetime in seconds, 60..600. Omit for the 600s default.","example":600,"maximum":600,"minimum":60}},"required":["actorUserId","reason"]},"ServerImpersonationTokenResponse":{"type":"object","description":"A minted impersonation token.","properties":{"token":{"type":"string","description":"The single-use token. Redeem via POST /_torii/auth/session/impersonate, or hand the ready-to-use `url` to an operator."},"expiresInSeconds":{"type":"integer","format":"int64","description":"The token's lifetime in seconds (the resolved value after any override).","example":600},"url":{"type":["string","null"],"description":"A ready-to-use, navigable redeem link on the environment's Frontend API host. Opening it in a browser establishes the impersonated session and redirects to the landing URL. Backed by the same single-use token. Null when no landing URL could be resolved (no `redirectUrl` given and the environment has no concrete allowed origin) — redeem the `token` via POST instead.","example":"https://auth.example.com/_torii/auth/session/impersonate?token=…"}},"required":["expiresInSeconds","token"]},"ServerUserSearchRequest":{"type":"object","description":"Optional filter body for `POST /users/search`. Every field is tri-state: omit to skip that filter, send a value to apply it. The three id-selectors (`userIds`, `emailAddresses`, `email`) resolve users to a set of ids and, when more than one is supplied, are combined with AND (intersection); a supplied id-selector whose resolved set is empty returns an empty page. `name` additionally accepts JSON null to match users with no name; an explicit null or blank `email` contributes no restriction; the non-nullable `statuses` field rejects null.","properties":{"name":{"type":["string","null"],"description":"Filter by name (case-insensitive substring match). Send null to require users with no name.","example":"Ada"},"userIds":{"type":"array","description":"Restrict to these user ids (the explicit batch-by-id lookup), at most 100. AND-combined with the other id-selectors; an empty list returns an empty page.","example":["01931a73-8b00-7000-8000-000000000000"],"items":{"type":"string","format":"uuid"}},"emailAddresses":{"type":"array","description":"Resolve users by exact (case-insensitive) email address (one or more, at most 100). Unlike `email`, never matches a superstring. AND-combined with the other id-selectors; an empty list, or addresses matching nobody, returns an empty page.","example":["ada@example.com"],"items":{"type":"string"}},"email":{"type":["string","null"],"description":"Filter by primary email (case-insensitive substring match). AND-combined with the other id-selectors. An explicit null or blank value contributes no restriction.","example":"@example.com"},"statuses":{"type":"array","description":"Filter by user status. Returns users matching any of the supplied statuses.","items":{"type":"string","enum":["active","banned","deleted"]},"uniqueItems":true},"createdAfter":{"type":["string","null"],"format":"date-time","description":"Only return users created at or after this instant (ISO-8601 UTC).","example":"2026-01-01T00:00:00Z"},"createdBefore":{"type":["string","null"],"format":"date-time","description":"Only return users created at or before this instant (ISO-8601 UTC).","example":"2026-12-31T23:59:59Z"}}},"CursorPageResponseServerUserResponse":{"type":"object","description":"A single page of results in a cursor-paginated list. Pass `nextCursor` as the `cursor` query parameter to fetch the following page.","properties":{"items":{"type":"array","description":"Items in this page, in stable order.","items":{"$ref":"#/components/schemas/ServerUserResponse"}},"nextCursor":{"type":["string","null"],"format":"uuid","description":"Cursor to pass to fetch the next page. Null when this is the last page.","example":"01931a73-8b00-7000-8000-000000000000"},"hasMore":{"type":"boolean","description":"True if more pages are available (equivalent to `nextCursor != null`).","example":true}},"required":["hasMore","items"]},"CreateEnvironmentInvitationServerRequest":{"type":"object","properties":{"email":{"type":"string"},"expiresInDays":{"type":["integer","null"],"format":"int32"},"redirectUrl":{"type":["string","null"]},"publicMetadata":{"type":"object","additionalProperties":true},"privateMetadata":{"type":"object","additionalProperties":true}},"required":["email","privateMetadata","publicMetadata"]},"EnvironmentInvitationResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"email":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","REVOKED","EXPIRED"]},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"}},"required":["createdAt","email","environmentId","expiresAt","id","status"]},"UpdateUserRequest":{"type":"object","description":"PATCH body for updating an end-user. Every field is tri-state: omit the key entirely to leave the field unchanged, send a non-null value to set it, or send JSON null to clear it.","properties":{"firstName":{"type":["string","null"],"description":"New first (given) name. Send null to clear; omit to leave unchanged.","example":"Ada"},"lastName":{"type":["string","null"],"description":"New last (family) name. Send null to clear; omit to leave unchanged.","example":"Lovelace"},"locale":{"type":["string","null"],"description":"New preferred locale. Send null to clear; omit to leave unchanged.","enum":["en","da"]},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Deep-merges into the user's unsafe metadata (a key set to null removes it); omit to leave unchanged. Counts toward the 8 KB combined metadata budget.","example":{"onboardingStep":2}}}},"UpdateUserMetadataRequest":{"type":"object","description":"PATCH body for a user's metadata bags. Each bag is tri-state: omit to leave it unchanged, or send an object value. Whether the object merges into or replaces the bag depends on the endpoint (see its operation description).","properties":{"publicMetadata":{"type":"object","additionalProperties":true,"description":"Public metadata bag: SDK-readable, server-written. Part of the 8 KB combined metadata budget.","example":{"plan":"pro"}},"privateMetadata":{"type":"object","additionalProperties":true,"description":"Private metadata bag: server-only, never exposed to the SDK or in a JWT. Part of the 8 KB combined metadata budget.","example":{"billingCustomerId":"cus_123"}},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Unsafe metadata bag: readable and writable by the end-user via the SDK. Part of the 8 KB combined metadata budget.","example":{"onboardingStep":2}}}},"UserSessionResponse":{"type":"object","description":"An active end-user session in your environment.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for this session.","example":"01931a74-1234-7000-8000-000000000000"},"userId":{"type":"string","format":"uuid","description":"Identifier of the end-user this session belongs to.","example":"01931a73-8b00-7000-8000-000000000000"},"environmentId":{"type":"string","format":"uuid","description":"Identifier of the environment this session belongs to.","example":"01931a72-0000-7000-8000-000000000000"},"userAgent":{"type":["string","null"],"description":"Raw User-Agent string captured when the session was created.","example":"Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6_0) AppleWebKit/537.36"},"ipAddress":{"type":["string","null"],"description":"IP address captured when the session was created.","example":"203.0.113.42"},"createdAt":{"type":"string","format":"date-time","description":"When this session was created (ISO-8601 UTC).","example":"2026-05-16T09:30:00Z"},"expiresAt":{"type":"string","format":"date-time","description":"When this session expires (ISO-8601 UTC).","example":"2026-05-23T09:30:00Z"},"lastUsedAt":{"type":"string","format":"date-time","description":"When this session was last seen by the API (ISO-8601 UTC).","example":"2026-05-16T11:42:00Z"},"activeOrganizationId":{"type":["string","null"],"format":"uuid","description":"Active organization pinned to this session (`org_id` claim on re-mint)."},"impersonatedBy":{"type":["string","null"],"format":"uuid","description":"Platform user behind this session when it was established via impersonation; null for normal sign-ins."}},"required":["createdAt","environmentId","expiresAt","id","lastUsedAt","userId"]},"CursorPageResponseEnvironmentInvitationResponse":{"type":"object","description":"A single page of results in a cursor-paginated list. Pass `nextCursor` as the `cursor` query parameter to fetch the following page.","properties":{"items":{"type":"array","description":"Items in this page, in stable order.","items":{"$ref":"#/components/schemas/EnvironmentInvitationResponse"}},"nextCursor":{"type":["string","null"],"format":"uuid","description":"Cursor to pass to fetch the next page. Null when this is the last page.","example":"01931a73-8b00-7000-8000-000000000000"},"hasMore":{"type":"boolean","description":"True if more pages are available (equivalent to `nextCursor != null`).","example":true}},"required":["hasMore","items"]}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Backend secret key (`sk_live_*` / `sk_test_*`) sent as `Authorization: Bearer <key>`.","scheme":"bearer"}}}}

data/src/torii/backend/generated/lib/torii_backend_generated/api/server_impersonation_api.rb

@@ -20,7 +20,7 @@ module ToriiBackendGenerated
       @api_client = api_client
     end
     # Mint an impersonation token
-    # Creates a single-use, short-lived impersonation token for the target user, attributed to `actorUserId`. Redeem it via `POST /_torii/auth/session/impersonate` to obtain a session and access token as the target user. Counts against the same per-period impersonation quota and usage ledger as the dashboard.
+    # Creates a single-use, short-lived impersonation token for the target user, attributed to `actorUserId`. Redeem it programmatically via `POST /_torii/auth/session/impersonate` (access token in the body), or hand the returned `url` to an operator to open in a browser (establishes the session and redirects to the landing URL). Counts against the same per-period impersonation quota and usage ledger as the dashboard.
     # @param user_id [String] The user to impersonate.
     # @param server_impersonation_token_request [ServerImpersonationTokenRequest] 
     # @param [Hash] opts the optional parameters
@@ -31,7 +31,7 @@ module ToriiBackendGenerated
     end
 
     # Mint an impersonation token
-    # Creates a single-use, short-lived impersonation token for the target user, attributed to `actorUserId`. Redeem it via `POST /_torii/auth/session/impersonate` to obtain a session and access token as the target user. Counts against the same per-period impersonation quota and usage ledger as the dashboard.
+    # Creates a single-use, short-lived impersonation token for the target user, attributed to `actorUserId`. Redeem it programmatically via `POST /_torii/auth/session/impersonate` (access token in the body), or hand the returned `url` to an operator to open in a browser (establishes the session and redirects to the landing URL). Counts against the same per-period impersonation quota and usage ledger as the dashboard.
     # @param user_id [String] The user to impersonate.
     # @param server_impersonation_token_request [ServerImpersonationTokenRequest] 
     # @param [Hash] opts the optional parameters

data/src/torii/backend/generated/lib/torii_backend_generated/models/server_impersonation_token_request.rb

@@ -22,7 +22,10 @@ module ToriiBackendGenerated
     # Mandatory justification (GDPR purpose limitation); recorded in the audit log on mint and redeem.
     attr_accessor :reason
 
-    # Optional token lifetime in seconds, 60..600. Omit for the 60s default.
+    # Optional post-redeem landing URL for the `url` redeem link; its origin must be in the environment's allowed origins. Omit to default to the environment's first non-wildcard allowed origin.
+    attr_accessor :redirect_url
+
+    # Optional token lifetime in seconds, 60..600. Omit for the 600s default.
     attr_accessor :expires_in_seconds
 
     # Attribute mapping from ruby-style variable name to JSON key.
@@ -30,6 +33,7 @@ module ToriiBackendGenerated
       {
         :'actor_user_id' => :'actorUserId',
         :'reason' => :'reason',
+        :'redirect_url' => :'redirectUrl',
         :'expires_in_seconds' => :'expiresInSeconds'
       }
     end
@@ -49,6 +53,7 @@ module ToriiBackendGenerated
       {
         :'actor_user_id' => :'String',
         :'reason' => :'String',
+        :'redirect_url' => :'String',
         :'expires_in_seconds' => :'Integer'
       }
     end
@@ -56,6 +61,7 @@ module ToriiBackendGenerated
     # List of attributes with nullable: true
     def self.openapi_nullable
       Set.new([
+        :'redirect_url',
         :'expires_in_seconds'
       ])
     end
@@ -88,6 +94,10 @@ module ToriiBackendGenerated
         self.reason = nil
       end
 
+      if attributes.key?(:'redirect_url')
+        self.redirect_url = attributes[:'redirect_url']
+      end
+
       if attributes.key?(:'expires_in_seconds')
         self.expires_in_seconds = attributes[:'expires_in_seconds']
       end
@@ -187,6 +197,7 @@ module ToriiBackendGenerated
       self.class == o.class &&
           actor_user_id == o.actor_user_id &&
           reason == o.reason &&
+          redirect_url == o.redirect_url &&
           expires_in_seconds == o.expires_in_seconds
     end
 
@@ -199,7 +210,7 @@ module ToriiBackendGenerated
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [actor_user_id, reason, expires_in_seconds].hash
+      [actor_user_id, reason, redirect_url, expires_in_seconds].hash
     end
 
     # Builds the object from hash

data/src/torii/backend/generated/lib/torii_backend_generated/models/server_impersonation_token_response.rb

@@ -16,17 +16,21 @@ require 'time'
 module ToriiBackendGenerated
   # A minted impersonation token.
   class ServerImpersonationTokenResponse < ApiModelBase
-    # The single-use token. Redeem via POST /_torii/auth/session/impersonate.
+    # The single-use token. Redeem via POST /_torii/auth/session/impersonate, or hand the ready-to-use `url` to an operator.
     attr_accessor :token
 
     # The token's lifetime in seconds (the resolved value after any override).
     attr_accessor :expires_in_seconds
 
+    # A ready-to-use, navigable redeem link on the environment's Frontend API host. Opening it in a browser establishes the impersonated session and redirects to the landing URL. Backed by the same single-use token. Null when no landing URL could be resolved (no `redirectUrl` given and the environment has no concrete allowed origin) — redeem the `token` via POST instead.
+    attr_accessor :url
+
     # Attribute mapping from ruby-style variable name to JSON key.
     def self.attribute_map
       {
         :'token' => :'token',
-        :'expires_in_seconds' => :'expiresInSeconds'
+        :'expires_in_seconds' => :'expiresInSeconds',
+        :'url' => :'url'
       }
     end
 
@@ -44,13 +48,15 @@ module ToriiBackendGenerated
     def self.openapi_types
       {
         :'token' => :'String',
-        :'expires_in_seconds' => :'Integer'
+        :'expires_in_seconds' => :'Integer',
+        :'url' => :'String'
       }
     end
 
     # List of attributes with nullable: true
     def self.openapi_nullable
       Set.new([
+        :'url'
       ])
     end
 
@@ -81,6 +87,10 @@ module ToriiBackendGenerated
       else
         self.expires_in_seconds = nil
       end
+
+      if attributes.key?(:'url')
+        self.url = attributes[:'url']
+      end
     end
 
     # Show invalid properties with the reasons. Usually used together with valid?
@@ -134,7 +144,8 @@ module ToriiBackendGenerated
       return true if self.equal?(o)
       self.class == o.class &&
           token == o.token &&
-          expires_in_seconds == o.expires_in_seconds
+          expires_in_seconds == o.expires_in_seconds &&
+          url == o.url
     end
 
     # @see the `==` method
@@ -146,7 +157,7 @@ module ToriiBackendGenerated
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [token, expires_in_seconds].hash
+      [token, expires_in_seconds, url].hash
     end
 
     # Builds the object from hash

data/src/torii/backend/version.rb

@@ -2,6 +2,6 @@
 
 module Torii
   module Backend
-    VERSION = '0.0.8'
+    VERSION = '0.0.9'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: torii-backend
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - torii
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt