torii-backend 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b25f66d30b4e23638dd95bc34fafd38fc91ff3535d4f9559f72fdb96fd6a6606
-  data.tar.gz: e872022b3162234a4a76183d37147bc5be583afef6175ff1ae24e3d4868e50e2
+  metadata.gz: 69a7cc52abd5b85f92c4d597f712da8c6f025de4aa486abf6a35bbd8fc136128
+  data.tar.gz: 8ace55761be96d67053626cacbd34cb5e823130bdd9f5e00499a13d6c048ec36
 SHA512:
-  metadata.gz: e62519cf17851517cdaf1b77cca4b2601488051f54a347500db0f779d88b0856eab0aed51885a615bea5772e31acdc1eca9e5782816ad901663b3e84f31128ec
-  data.tar.gz: 752fa2c814044fd51ca5d1cf36db9571744f2ee0424a0575ecee8eb5d6a2d5429df77443c2738e3ea3be1c2e2c962dcebfc92603b029e91416203938ce4a8c06
+  metadata.gz: 423343331cb1efb385dd06a91643fd65494996c5e20945c049f399ecf5aeea0dd718c47271956560866b17f9660fa706952f873c6f395f3693424f15d8cdaaad
+  data.tar.gz: 18e2ef7a673af34fbaf5776d39f8fa43de03589049ce5a111ed3cca831abf7bff1ce193d728de56499b96bc884238e1020baf87db9046a32d796c35d3bfe5ee4

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 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}/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. Filters use the same tri-state PATCH semantics as `UpdateUserRequest`: omit a field to skip that filter, send a value to require it, send null to require null. Uses POST so the filter body can be sent without URL-encoding.","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"}}}},"401":{"description":"Missing or invalid secret key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/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 result is capped at 512 bytes for `publicMetadata`/`unsafeMetadata` and 4096 bytes for `privateMetadata`.","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/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). Max 512 bytes.","example":{"plan":"free"}},"privateMetadata":{"type":"object","additionalProperties":true,"description":"Initial private metadata (server-only). Max 4096 bytes.","example":{"stripeId":"cus_123"}},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Initial unsafe metadata (end-user writable). Max 512 bytes.","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":{"stripeId":"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"]},"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 require it. Fields whose inner type is nullable (currently `name`, `email`) additionally accept JSON null to filter for users where that column is null; 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"},"email":{"type":["string","null"],"description":"Filter by primary email (case-insensitive substring match). Send null to require users with no email.","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"]},"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. Merged result max 512 bytes.","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. Max 512 bytes.","example":{"plan":"pro"}},"privateMetadata":{"type":"object","additionalProperties":true,"description":"Private metadata bag: server-only, never exposed to the SDK or in a JWT. Max 4096 bytes.","example":{"stripeId":"cus_123"}},"unsafeMetadata":{"type":"object","additionalProperties":true,"description":"Unsafe metadata bag: readable and writable by the end-user via the SDK. Max 512 bytes.","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"]}},"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 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"}}}}

data/src/torii/backend/client.rb

@@ -136,17 +136,21 @@ module Torii
       # JSON keys the server expects (camelCase).
       def update(user_id, **patches)
         body = {}
+        # Source the snake_case -> camelCase mapping from the generated model's
+        # attribute_map, so a new patchable field flows through with zero hand
+        # edits (an unknown field still raises).
+        attribute_map = ToriiBackendGenerated::UpdateUserRequest.attribute_map
         patches.each do |field, patch|
           unless patch.is_a?(Patch)
             raise ArgumentError, "kwarg #{field} must be a Torii::Backend::Patch (got #{patch.class})"
           end
 
-          json_key = PATCH_FIELD_MAP.fetch(field) do
-            raise ArgumentError, "unknown PATCH field: #{field}. Valid: #{PATCH_FIELD_MAP.keys.inspect}"
+          json_key = attribute_map.fetch(field) do
+            raise ArgumentError, "unknown PATCH field: #{field}. Valid: #{attribute_map.keys.inspect}"
           end
 
           # Patch.set(value) emits the key; nil value → JSON null (clear).
-          body[json_key] = patch.value
+          body[json_key.to_s] = patch.value
         end
 
         # +debug_body+ on the generated client is the escape hatch for
@@ -163,16 +167,6 @@ module Torii
         model_to_hash(result)
       end
 
-      # Map of Ruby snake_case kwargs to the JSON keys the server
-      # expects on the PATCH body. Centralised so +update+ can validate
-      # field names with a single +fetch+.
-      PATCH_FIELD_MAP = {
-        first_name: 'firstName',
-        last_name: 'lastName',
-        locale: 'locale',
-        unsafe_metadata: 'unsafeMetadata',
-      }.freeze
-
       def delete(user_id)
         @api.delete_user(user_id)
         nil

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

@@ -0,0 +1,336 @@
+=begin
+#Torii Backend API
+
+#Server-to-server API (BAPI) for backend SDKs. Authenticated with a secret key (Bearer sk_live_* / sk_test_*).
+
+The version of the OpenAPI document: v1
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.22.0
+
+=end
+
+require 'cgi'
+
+module ToriiBackendGenerated
+  class InvitationsApi
+    attr_accessor :api_client
+
+    def initialize(api_client = ApiClient.default)
+      @api_client = api_client
+    end
+    # Create an invitation with optional pre-seeded metadata
+    # @param create_environment_invitation_server_request [CreateEnvironmentInvitationServerRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [EnvironmentInvitationResponse]
+    def create(create_environment_invitation_server_request, opts = {})
+      data, _status_code, _headers = create_with_http_info(create_environment_invitation_server_request, opts)
+      data
+    end
+
+    # Create an invitation with optional pre-seeded metadata
+    # @param create_environment_invitation_server_request [CreateEnvironmentInvitationServerRequest] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(EnvironmentInvitationResponse, Integer, Hash)>] EnvironmentInvitationResponse data, response status code and response headers
+    def create_with_http_info(create_environment_invitation_server_request, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: InvitationsApi.create ...'
+      end
+      # verify the required parameter 'create_environment_invitation_server_request' is set
+      if @api_client.config.client_side_validation && create_environment_invitation_server_request.nil?
+        fail ArgumentError, "Missing the required parameter 'create_environment_invitation_server_request' when calling InvitationsApi.create"
+      end
+      # resource path
+      local_var_path = '/api/server/v1/invitations'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+      # HTTP header 'Content-Type'
+      content_type = @api_client.select_header_content_type(['application/json'])
+      if !content_type.nil?
+          header_params['Content-Type'] = content_type
+      end
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(create_environment_invitation_server_request)
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'EnvironmentInvitationResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"InvitationsApi.create",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: InvitationsApi#create\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Get an invitation by id
+    # @param invitation_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [EnvironmentInvitationResponse]
+    def get(invitation_id, opts = {})
+      data, _status_code, _headers = get_with_http_info(invitation_id, opts)
+      data
+    end
+
+    # Get an invitation by id
+    # @param invitation_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(EnvironmentInvitationResponse, Integer, Hash)>] EnvironmentInvitationResponse data, response status code and response headers
+    def get_with_http_info(invitation_id, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: InvitationsApi.get ...'
+      end
+      # verify the required parameter 'invitation_id' is set
+      if @api_client.config.client_side_validation && invitation_id.nil?
+        fail ArgumentError, "Missing the required parameter 'invitation_id' when calling InvitationsApi.get"
+      end
+      # resource path
+      local_var_path = '/api/server/v1/invitations/{invitationId}'.sub('{invitationId}', CGI.escape(invitation_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'EnvironmentInvitationResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"InvitationsApi.get",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: InvitationsApi#get\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # List invitations for this environment
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :status 
+    # @option opts [String] :search 
+    # @option opts [Integer] :limit  (default to 20)
+    # @option opts [String] :cursor 
+    # @return [CursorPageResponseEnvironmentInvitationResponse]
+    def list1(opts = {})
+      data, _status_code, _headers = list1_with_http_info(opts)
+      data
+    end
+
+    # List invitations for this environment
+    # @param [Hash] opts the optional parameters
+    # @option opts [Array<String>] :status 
+    # @option opts [String] :search 
+    # @option opts [Integer] :limit  (default to 20)
+    # @option opts [String] :cursor 
+    # @return [Array<(CursorPageResponseEnvironmentInvitationResponse, Integer, Hash)>] CursorPageResponseEnvironmentInvitationResponse data, response status code and response headers
+    def list1_with_http_info(opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: InvitationsApi.list1 ...'
+      end
+      # resource path
+      local_var_path = '/api/server/v1/invitations'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'status'] = @api_client.build_collection_param(opts[:'status'], :multi) if !opts[:'status'].nil?
+      query_params[:'search'] = opts[:'search'] if !opts[:'search'].nil?
+      query_params[:'limit'] = opts[:'limit'] if !opts[:'limit'].nil?
+      query_params[:'cursor'] = opts[:'cursor'] if !opts[:'cursor'].nil?
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'CursorPageResponseEnvironmentInvitationResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"InvitationsApi.list1",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: InvitationsApi#list1\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Resend a pending invitation with a fresh link
+    # @param invitation_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [EnvironmentInvitationResponse]
+    def resend(invitation_id, opts = {})
+      data, _status_code, _headers = resend_with_http_info(invitation_id, opts)
+      data
+    end
+
+    # Resend a pending invitation with a fresh link
+    # @param invitation_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(EnvironmentInvitationResponse, Integer, Hash)>] EnvironmentInvitationResponse data, response status code and response headers
+    def resend_with_http_info(invitation_id, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: InvitationsApi.resend ...'
+      end
+      # verify the required parameter 'invitation_id' is set
+      if @api_client.config.client_side_validation && invitation_id.nil?
+        fail ArgumentError, "Missing the required parameter 'invitation_id' when calling InvitationsApi.resend"
+      end
+      # resource path
+      local_var_path = '/api/server/v1/invitations/{invitationId}/resend'.sub('{invitationId}', CGI.escape(invitation_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json']) unless header_params['Accept']
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'EnvironmentInvitationResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"InvitationsApi.resend",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:POST, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: InvitationsApi#resend\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
+    # Revoke a pending invitation
+    # @param invitation_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [nil]
+    def revoke(invitation_id, opts = {})
+      revoke_with_http_info(invitation_id, opts)
+      nil
+    end
+
+    # Revoke a pending invitation
+    # @param invitation_id [String] 
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def revoke_with_http_info(invitation_id, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: InvitationsApi.revoke ...'
+      end
+      # verify the required parameter 'invitation_id' is set
+      if @api_client.config.client_side_validation && invitation_id.nil?
+        fail ArgumentError, "Missing the required parameter 'invitation_id' when calling InvitationsApi.revoke"
+      end
+      # resource path
+      local_var_path = '/api/server/v1/invitations/{invitationId}'.sub('{invitationId}', CGI.escape(invitation_id.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['bearerAuth']
+
+      new_options = opts.merge(
+        :operation => :"InvitationsApi.revoke",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:DELETE, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: InvitationsApi#revoke\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+  end
+end