torii-backend 0.0.2__tar.gz

torii_backend-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Match the python versions listed in pyproject.toml classifiers.
+        python: ['3.9', '3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install uv (matches CONTRIBUTING.md dev flow)
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+
+      - name: Ruff (lint)
+        run: .venv/bin/ruff check src/torii_backend tests
+
+      - name: Pytest
+        run: .venv/bin/pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Verify wheel installs cleanly
+        run: |
+          python -m venv /tmp/verify-venv
+          /tmp/verify-venv/bin/pip install dist/*.whl
+          /tmp/verify-venv/bin/python -c "import torii_backend; print(torii_backend.__name__)"

torii_backend-0.0.2/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+# Tag-triggered PyPI publish via OIDC trusted publishing.
+#
+# Prerequisites (one-time, see torii repo docs/Publishing-SDKs.md):
+#   1. pypi.org → "Your projects" → "Publishing" → Add pending publisher
+#      (or, after first publish, regular trusted publisher) with:
+#        - PyPI project name: torii-backend
+#        - Owner: Torii-ApS
+#        - Repository: torii-sdk-python
+#        - Workflow: release.yml
+#        - Environment: pypi
+#   2. GitHub repo → Settings → Environments → create `pypi` with required
+#      reviewers for manual approval before publish.
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write     # for GH release creation
+  id-token: write     # required for OIDC trusted publishing
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Assert tag matches pyproject.toml version
+        run: |
+          PKG_VERSION=$(python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${PKG_VERSION}" >&2
+            exit 1
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Test on tagged SHA
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+          .venv/bin/pytest -q
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No `with: password` — OIDC trusted publisher exchanges the
+        # GitHub-issued ID token for a short-lived PyPI upload token.
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes

torii_backend-0.0.2/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.DS_Store
+.idea/
+.vscode/

torii_backend-0.0.2/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Thanks for your interest in `torii-backend`!
+
+## Reporting bugs
+
+Open an issue with:
+
+- The version of `torii-backend` you're using (`pip show torii-backend`).
+- A minimal reproduction — a few lines that exhibit the bug.
+- What you expected to happen vs. what actually happened.
+
+For security-sensitive issues (anything that could let an attacker forge or bypass token verification), please email **security@torii.so** instead of filing a public issue.
+
+## Development
+
+```sh
+git clone https://github.com/Torii-ApS/torii-sdk-python
+cd torii-sdk-python
+uv venv
+uv pip install -e ".[dev]"
+.venv/bin/pytest -q
+```
+
+The REST client under `src/torii_backend/generated/` is produced by [`openapi-generator`](https://openapi-generator.tech/) from `spec/server-v1.json`. Don't hand-edit it. To regenerate after a spec update:
+
+```sh
+bunx -y @openapitools/openapi-generator-cli generate \
+  -i spec/server-v1.json -g python -o /tmp/python-gen-raw \
+  --additional-properties=packageName=torii_backend.generated,projectName=torii-backend-generated,library=urllib3
+cp -r /tmp/python-gen-raw/torii_backend/generated src/torii_backend/generated
+```
+
+The hand-written surface (`client.py`, `verify.py`, `fastapi.py`, `types.py`, `errors.py`) is where bug reports and PRs typically land.
+
+## Pull requests
+
+1. Open an issue first for non-trivial changes so we can discuss the shape.
+2. Branch off `main`, name it `fix/<short>` or `feat/<short>`.
+3. Run `.venv/bin/ruff check src/torii_backend tests` and `.venv/bin/pytest -q` before pushing — CI checks both across Python 3.9–3.12.
+4. Keep PRs small and focused. One concern per PR.
+5. Update `README.md` if you change the public surface.
+
+## Releases
+
+Tagged off `main`. Bump `version` in `pyproject.toml` and any references in `README.md`, then:
+
+```sh
+git tag v0.0.2
+git push origin v0.0.2
+```
+
+Publishing to PyPI is handled by a maintainer; ping in the release PR if you need a cut.
+
+## Code of Conduct
+
+Be kind. Disagreements happen; argue the position, not the person.

torii_backend-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GOOD Code ApS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

torii_backend-0.0.2/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: torii-backend
+Version: 0.0.2
+Summary: Backend SDK for torii — verify JWTs, manage users, react to events from your Python server.
+Project-URL: Homepage, https://torii.so
+Project-URL: Source, https://github.com/Torii-ApS/torii-sdk-python
+Project-URL: Issues, https://github.com/Torii-ApS/torii-sdk-python/issues
+Author: GOOD Code ApS
+License: MIT
+License-File: LICENSE
+Keywords: auth,backend,jwt,oidc,torii
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.11
+Requires-Dist: pyjwt[crypto]<3.0,>=2.8
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: typing-extensions>=4.7.1
+Requires-Dist: urllib3<3.0.0,>=2.1.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# torii-backend
+
+Backend SDK for [torii](https://torii.so) — verify end-user JWTs without a per-request round trip and manage users from your Python server.
+
+> **v0.x — API may still change.**
+
+## Setup
+
+1. Sign in to [app.torii.so](https://app.torii.so) and from your dashboard copy:
+   - your **issuer URL** (e.g. `https://acme.torii.so`)
+   - a **secret key** (`sk_test_…` for development, `sk_live_…` for production)
+
+2. Install the SDK:
+
+   ```sh
+   pip install torii-backend
+   # or, with the FastAPI dependency adapter:
+   pip install "torii-backend[fastapi]"
+   ```
+
+   Python 3.9+.
+
+3. Verify an end-user JWT:
+
+   ```python
+   from torii_backend import verify_token
+
+   auth = verify_token(token, issuer="https://acme.torii.so")
+   print(auth.user_id, auth.environment_id, auth.email_verified)
+   ```
+
+   The first call fetches the issuer's JWKS; subsequent calls reuse the cache and rotate keys automatically (handled by [`PyJWT`](https://pyjwt.readthedocs.io/)). No round trip per request.
+
+4. Call the backend REST API:
+
+   ```python
+   import os
+   from torii_backend import create_torii_client
+
+   torii = create_torii_client(secret_key=os.environ["TORII_SECRET_KEY"])
+   user = torii.users.get(user_id)
+   ```
+
+   Default base URL is `https://api.torii.so`. Override with `api_url=` for staging or self-hosted.
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from torii_backend.fastapi import require_auth
+
+app = FastAPI()
+auth_dep = require_auth(issuer="https://acme.torii.so")
+
+@app.get("/me")
+def me(auth = Depends(auth_dep)):
+    return {"user_id": auth.user_id}
+```
+
+## Backend API
+
+```python
+page = torii.users.list(limit=50)
+user = torii.users.create(email="x@y.com")
+torii.users.ban(user.id)
+
+sessions = torii.sessions.list_for_user(user.id)
+torii.sessions.revoke_all_for_user(user.id)
+```
+
+### PATCH semantics (`users.update`)
+
+`users.update` is a tri-state PATCH: each updatable field can be **set**, **cleared**, or **left alone**. Pass only the kwargs you want on the wire — pydantic v2's `model_fields_set` tracks which fields were explicitly provided, and the SDK serializes via `model_dump(exclude_unset=True)` so untouched fields never appear in the request body.
+
+```python
+torii.users.update(
+    user_id,
+    name="Ada",     # → server updates name
+    phone=None,     # → server clears phone (sent as JSON null)
+    # address not passed → server leaves alone
+)
+```
+
+Wire body for the call above:
+
+```json
+{ "name": "Ada", "phone": null }
+```
+
+| Call                                  | Field on wire     | Server effect      |
+| ------------------------------------- | ----------------- | ------------------ |
+| `users.update(id, name="Ada")`        | `"name": "Ada"`   | update `name`      |
+| `users.update(id, phone=None)`        | `"phone": null`   | clear `phone`      |
+| `users.update(id)` (no field kwargs)  | omitted           | leave alone        |
+
+You can also build a request explicitly — useful when assembling the patch dynamically:
+
+```python
+from torii_backend import ToriiUpdateUserInput
+
+patch = ToriiUpdateUserInput(name="Ada", phone=None)
+torii.users.update(user_id, patch)
+```
+
+## License
+
+MIT

torii_backend-0.0.2/README.md

@@ -0,0 +1,107 @@
+# torii-backend
+
+Backend SDK for [torii](https://torii.so) — verify end-user JWTs without a per-request round trip and manage users from your Python server.
+
+> **v0.x — API may still change.**
+
+## Setup
+
+1. Sign in to [app.torii.so](https://app.torii.so) and from your dashboard copy:
+   - your **issuer URL** (e.g. `https://acme.torii.so`)
+   - a **secret key** (`sk_test_…` for development, `sk_live_…` for production)
+
+2. Install the SDK:
+
+   ```sh
+   pip install torii-backend
+   # or, with the FastAPI dependency adapter:
+   pip install "torii-backend[fastapi]"
+   ```
+
+   Python 3.9+.
+
+3. Verify an end-user JWT:
+
+   ```python
+   from torii_backend import verify_token
+
+   auth = verify_token(token, issuer="https://acme.torii.so")
+   print(auth.user_id, auth.environment_id, auth.email_verified)
+   ```
+
+   The first call fetches the issuer's JWKS; subsequent calls reuse the cache and rotate keys automatically (handled by [`PyJWT`](https://pyjwt.readthedocs.io/)). No round trip per request.
+
+4. Call the backend REST API:
+
+   ```python
+   import os
+   from torii_backend import create_torii_client
+
+   torii = create_torii_client(secret_key=os.environ["TORII_SECRET_KEY"])
+   user = torii.users.get(user_id)
+   ```
+
+   Default base URL is `https://api.torii.so`. Override with `api_url=` for staging or self-hosted.
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from torii_backend.fastapi import require_auth
+
+app = FastAPI()
+auth_dep = require_auth(issuer="https://acme.torii.so")
+
+@app.get("/me")
+def me(auth = Depends(auth_dep)):
+    return {"user_id": auth.user_id}
+```
+
+## Backend API
+
+```python
+page = torii.users.list(limit=50)
+user = torii.users.create(email="x@y.com")
+torii.users.ban(user.id)
+
+sessions = torii.sessions.list_for_user(user.id)
+torii.sessions.revoke_all_for_user(user.id)
+```
+
+### PATCH semantics (`users.update`)
+
+`users.update` is a tri-state PATCH: each updatable field can be **set**, **cleared**, or **left alone**. Pass only the kwargs you want on the wire — pydantic v2's `model_fields_set` tracks which fields were explicitly provided, and the SDK serializes via `model_dump(exclude_unset=True)` so untouched fields never appear in the request body.
+
+```python
+torii.users.update(
+    user_id,
+    name="Ada",     # → server updates name
+    phone=None,     # → server clears phone (sent as JSON null)
+    # address not passed → server leaves alone
+)
+```
+
+Wire body for the call above:
+
+```json
+{ "name": "Ada", "phone": null }
+```
+
+| Call                                  | Field on wire     | Server effect      |
+| ------------------------------------- | ----------------- | ------------------ |
+| `users.update(id, name="Ada")`        | `"name": "Ada"`   | update `name`      |
+| `users.update(id, phone=None)`        | `"phone": null`   | clear `phone`      |
+| `users.update(id)` (no field kwargs)  | omitted           | leave alone        |
+
+You can also build a request explicitly — useful when assembling the patch dynamically:
+
+```python
+from torii_backend import ToriiUpdateUserInput
+
+patch = ToriiUpdateUserInput(name="Ada", phone=None)
+torii.users.update(user_id, patch)
+```
+
+## License
+
+MIT

torii_backend-0.0.2/openapitools.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "7.22.0"
+  }
+}

torii_backend-0.0.2/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "torii-backend"
+version = "0.0.2"
+description = "Backend SDK for torii — verify JWTs, manage users, react to events from your Python server."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "GOOD Code ApS" }]
+keywords = ["torii", "auth", "jwt", "oidc", "backend"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pyjwt[crypto]>=2.8,<3.0",
+    # Transitive deps of the openapi-generator output under
+    # `torii_backend.generated`. We name them here explicitly so the
+    # public dependency surface matches the published wheel.
+    "urllib3>=2.1.0,<3.0.0",
+    "pydantic>=2.11",
+    "python-dateutil>=2.8.2",
+    "typing-extensions>=4.7.1",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "fastapi>=0.100",
+]
+
+[project.urls]
+Homepage = "https://torii.so"
+Source = "https://github.com/Torii-ApS/torii-sdk-python"
+Issues = "https://github.com/Torii-ApS/torii-sdk-python/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/torii_backend"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+extend-exclude = ["src/torii_backend/generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"] # line length is handled by formatter
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+exclude = ["src/torii_backend/generated/"]
+
+[[tool.mypy.overrides]]
+module = "torii_backend.generated.*"
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+asyncio_mode = "auto"

torii_backend-0.0.2/spec/server-v1.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"http://localhost:52334","description":"Generated server url"}],"tags":[{"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/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/UserResponse"}}}},"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/UserResponse"}}}},"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/UserResponse"}}}},"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/CursorPageResponseUserResponse"}}}},"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/UserResponse"}}}},"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/UserResponse"}}}},"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}/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":{"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"},"name":{"type":["string","null"],"description":"Display name to seed on the profile.","example":"Ada Lovelace"},"phone":{"type":["string","null"],"description":"Phone number to seed on the profile.","example":"+15555550100"},"address":{"type":["string","null"],"description":"Postal address to seed on the profile.","example":"221B Baker Street, London"},"dateOfBirth":{"type":["string","null"],"format":"date","description":"Date of birth in ISO-8601 (YYYY-MM-DD).","example":"1815-12-10"}}},"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":{}}}},"UserResponse":{"type":"object","description":"An end-user belonging to one of your environments.","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"},"phone":{"type":["string","null"],"description":"Phone number on the profile, if any. Not guaranteed to be verified.","example":"+15555550100"},"locale":{"type":["string","null"],"description":"Preferred locale for emails and UI messages.","enum":["en","da"]},"address":{"type":["string","null"],"description":"Free-form address string, if provided.","example":"221B Baker Street, London"},"dateOfBirth":{"type":["string","null"],"format":"date","description":"Date of birth in ISO-8601 (YYYY-MM-DD), if provided.","example":"1815-12-10"},"status":{"type":"string","description":"Lifecycle status of the user (e.g. active, banned).","enum":["pending_verification","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. Not guaranteed to be verified.","example":"ada@example.com"},"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"}},"required":["createdAt","environmentId","id","status","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":["pending_verification","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"}}},"CursorPageResponseUserResponse":{"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/UserResponse"}},"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":{"name":{"type":["string","null"],"description":"New display name. Send null to clear; omit to leave unchanged.","example":"Ada Lovelace"},"phone":{"type":["string","null"],"description":"New phone number. Send null to clear; omit to leave unchanged.","example":"+15555550100"},"locale":{"type":["string","null"],"description":"New preferred locale. Send null to clear; omit to leave unchanged.","enum":["en","da"]},"address":{"type":["string","null"],"description":"New postal address. Send null to clear; omit to leave unchanged.","example":"221B Baker Street, London"},"dateOfBirth":{"type":["string","null"],"format":"date","description":"New date of birth (YYYY-MM-DD). Send null to clear; omit to leave unchanged.","example":"1815-12-10"}}},"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"}},"required":["createdAt","environmentId","expiresAt","id","lastUsedAt","userId"]}}}}