Web Console Api
The web console’s React apps read and change data through the web console api, a set of JSON
endpoints under /api/web/. It is the backend half of the
Django-React Integration, and the console’s own backend: the list, clone, rename and delete
actions of every resource list page, the dashboard’s widgets, the Prompt Passthrough’s providers,
the server log stream, and the like. Every path that the console’s pages fetch is under /api/,
and every other path is a page. The reasons are in
ADR-034: The Web Console Api.
How it differs from the public api
|
|
|
|---|---|---|
Clients |
The cli, the SDKs, any program |
The web console’s React apps only |
Authentication |
An api key, in the |
The browser’s Django session, with its CSRF token in the |
Compatibility |
Semantic versioning: a breaking change needs a new major version |
None: an endpoint changes with the page that calls it |
Documented in |
The OpenAPI document, at |
This page, and each endpoint’s docstring |
Shape |
Resources and commands |
Whatever the page needs, e.g. one dashboard widget’s rows |
Both call the same models, brokers and helpers. A generic operation that other clients would want
belongs in /api/v1/ too.
Layout
Each Django app mounts its endpoints at /api/web/<app label>/, from its own
api/web/urls.py, beside its api/v1/urls.py. smarter.apps.api.web.urls includes them
all, and smarter.apps.api.urls mounts it at web/. Each module has a reverse names class,
<App>ApiWebReverseNames, whose namespace is api:web:<app> and whose names are derived
from the view classes, as ADR-032 describes.
A React app never builds these urls itself. The Django view that renders its page reverses the url and passes it to the app in an attribute of its root element, as Django-React Integration describes:
from smarter.apps.guardrail.api.web.urls import GuardrailApiWebReverseNames
from smarter.lib.django.shortcuts import reverse
url = reverse(GuardrailApiWebReverseNames.namespace, GuardrailApiWebReverseNames.listview_all)
# "/api/web/guardrail/listview/"
The resource lists
Every resource list page has the same five endpoints, all POSTs, served by a
SmarterListApiView and its clone, rename and delete views.
The actions are siblings of listview/, so a React app derives them from its list url with
actionUrl() in @smarter/common.
Path |
Does |
|---|---|
|
One page of the list. See List Pagination, Search and Sorting. |
|
Copies the resource for the user. |
|
Renames it. |
|
Deletes it, unless something uses it. |
List |
Prefix |
Reverse names |
|---|---|---|
API Keys |
|
|
Budgets |
|
|
Connections |
|
|
Custom Domains |
|
|
Guardrails |
|
|
Infrastructure resources |
|
|
LLMClients (the workbench) |
|
|
LLMHosts |
|
|
LLMHost Computes |
|
|
LLM Tools |
|
|
MCPClients |
|
|
Orchestrators |
|
|
Providers |
|
|
Proxies |
|
|
Secrets |
|
|
Vector Searches |
|
|
Vector Stores |
|
|
Each list’s console page stays at its own path (/guardrail/, /secret/, …). Its view class
is named after its list api’s, e.g. GuardrailListView for GuardrailListApiView, which is how
listview_registry() pairs them.
The session
GET /api/web/session/ tells the console who is using it and how the platform is set up, in one
call: the signed-in user, the account the console acts for, the platform’s branding, which ways to
sign in are offered, which optional features are on, the languages, the state of the welcome dialog
and the onboarding hints, and the sidebar’s links and badge counts. A visitor who isn’t signed in gets
the same response with user, account, onboarding, welcome, badges and sidebar set
to null, which is all that the sign-in pages need.
The sidebar’s links are the urls of the server-rendered sidebar’s
(sidebar_context()). The backend decides which the user
has: a link that the platform has turned off, e.g. Proxies, or that the user may not use, e.g. the
Terminal and Infrastructure Resources for a superuser only and the Django admin for staff, is null.
The console decides the sections, their order, the labels and the icons. It is the one GET of this api, so that the console can call it
before it has a CSRF token, and it sets the CSRF cookie. It is never cached.
The single-page console (ADR-035) calls it when it starts, and
again after the user signs in, signs out or changes profile. Its response is
ConsoleSession, whose JSON Schema,
console-session.schema.json, is generated by manage.py export_console_session_schema. A test
fails if the committed copy is out of date.
Signing in
The console’s sign-in pages call the account api, under /api/web/account/. Signing in, signing out
and activating an account answer with the new session, so that the console needn’t ask for it again. A refused
request answers with AccountErrors: a message for the
whole form, and the messages of each field, which the console shows beside it.
Path |
Does |
|---|---|
|
Signs in with an email address and password. An unknown address and a wrong password get the
same answer, so that it doesn’t reveal which addresses have accounts. The right password of an
account that isn’t activated yet gets |
|
Signs out. The console’s sign-out, and the user menu’s Sign Out, call it. |
|
Creates an inactive user, and emails them a link to activate their account, while the
|
|
Activates the account of an emailed link, and signs its user in. Signing in uses the link up. |
|
Emails a new activation link, and answers the same whether or not the address has an account that is waiting to be activated. |
|
Emails a password reset link, and answers the same whether or not the address has an account. |
|
|
|
The user menu’s profile image: |
|
The user menu’s Download My Data: |
|
|
|
|
|
|
Signing in, signing up and asking for an activation or password reset link are limited to ten a
minute per IP address, by SmarterCredentialsRateThrottle, on top
of the api’s general rate limits. Every POST needs the CSRF token that the session api sets. Social
sign-in stays a redirect flow, through /social-auth/. The emailed links keep their paths, which the
console serves: /account/activate/<uidb64>/<token>/ and /password-reset-link/<uidb64>/<token>/.
A user who signs up with a password proves that the email address is theirs by following the activation
link (smarter.apps.account.activation). Users that social sign-in creates are inactive too, but an
administrator activates them, and they can’t ask for an activation link: see SOCIAL_AUTH_CREATE_USERS
in settings/base.py. The pipeline sends them to /account/inactive/ meanwhile, which the console
serves, as it does /account/already-associated/, for a social account that belongs to another user.
The other endpoints
Path |
Does |
|---|---|
|
The dashboard’s widgets, and its global search. See Dashboard. |
|
A resource’s manifest, hierarchy and dependents, for a list row’s detail, and for the console’s manifest pages, which know only the record locator: the kind is then the resource’s own. See Resource Detail. |
|
The welcome card and the onboarding tour. |
|
The Prompt Passthrough’s providers and their models, when
|
|
The user’s server log stream, when |
|
A one-time ticket that opens the Terminal’s WebSocket. |
|
The Prompt Engineer’s Workbench’s Manifest, Architecture and Deployment tabs, and the
Deployment tab’s api key actions. The workbench’s chat reads its configuration from the
public api, |
|
The Extensions console: |
Not yet in the web console api
One console endpoint remains beside its page: the Terminal’s WebSocket, ws/terminal/.
The workbench’s chat uses the public api, /api/v1/llm-clients/<hashed_id>/config/ and
prompt/, which a deployed LLMClient’s own host serves too.
Adding an endpoint
Write the view, e.g. a
SmarterListApiViewsubclass or aSmarterAuthenticatedNeverCachedWebViewthat returns JSON.Route it in the app’s
api/web/urls.py, named through its<App>ApiWebReverseNamesclass. An app that has none yet copiessmarter/apps/guardrail/api/web/urls.py, and adds itself tosmarter.apps.api.web.urls, behind the same feature flag as its page, if it has one.Reverse the url in the page’s view, and pass it to the React app in its root element’s attributes.
Test it through the class, and assert its path once. A resource list’s tests get all five endpoints from
ResourceViewsTestMixin, givenweb_reverse_names.
Technical Reference
The web console’s api, mounted at /api/web/.
This is the backend half of Smarter’s Django-React integration
(Django-React Integration). These are the endpoints that
the web console’s React apps call: the list, clone, rename and
delete actions of each resource list page, the dashboard’s widgets, and the like. They are
internal to the console. Unlike /api/v1/, they carry no compatibility promise, they are
not in the OpenAPI document, and they authenticate with the browser’s Django session and CSRF
token. See ADR-034: The Web Console Api and Web Console Api.
Constants for the web console’s api.
- smarter.apps.api.web.const.namespace = 'web'
The url namespace of the web console’s api, mounted at
/api/web/.
- smarter.apps.api.web.const.path_namespace = 'api:web'
The web console api’s namespaces from the root urlconf,
api:web.An app’s
api/web/urls.pyprefixes its own namespace with it, e.g.f"{path_namespace}:{namespace}"isapi:web:guardrail.
URL configuration for the web console’s api, mounted at /api/web/.
Each Django app that has a console page with a React app mounts its endpoints here, under its
app label, from its own api/web/urls.py, e.g. /api/web/guardrail/listview/. The
endpoints are internal to the web console: see smarter.apps.api.web.
These endpoints are part of Smarter’s Django-React integration. The Django view that renders a console page reverses their urls and passes them to the page’s React app, in the attributes of its root element, and the app calls them with the browser’s Django session and CSRF token. See Django-React Integration.
- class smarter.apps.api.web.urls.ApiWebReverseNames[source]
The names of the web console api’s own urls, the ones that belong to no Django app.
- console_session_view = 'console_session_view'
- namespace = 'api:web'
The contract of the web console’s session api, GET /api/web/session/, as Pydantic models.
The single-page console (ADR-035) calls it when it starts, and again after the user signs in, signs out or changes profile. It replaces what Django’s context processors and the React apps’ template tags put into each server-rendered page: who the user is, the account that the console acts for, the platform’s branding, which sign-in options and features are on, the languages, the SAM kinds, and the state of the welcome dialog and onboarding hints. The JSON is camelCase.
A request without a signed-in user gets a ConsoleSession whose user, account,
onboarding, welcome, badges and sidebar are null: what the sign-in pages need, and nothing about
any user.
manage.py export_console_session_schema writes the models’ JSON Schema to
console-session.schema.json, beside this module, from which @smarter/console generates its
TypeScript types (make console-session-contract). A test fails if the committed schema is out of date.
- class smarter.apps.api.web.session.contract.ConsoleAccount(**data)[source]
The account that the console acts for: that of the user’s selected profile.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleBadges(**data)[source]
The counts that the sidebar shows beside its items.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleBranding(**data)[source]
The platform’s identity and contacts, which the console shows in its header, footer and sign-in pages.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleCookies(**data)[source]
The names and domain of Django’s cookies, which the console’s api calls send.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleFlags(**data)[source]
The console’s optional features: which pages exist, and which tabs and widgets show.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleLanguage(**data)[source]
The console’s languages, and the one that this response, and the session, are in.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleLanguageOption(**data)[source]
A language that the console is translated into.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleOnboarding(**data)[source]
The state of the console’s onboarding hints for the user.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleSession(**data)[source]
Everything that the console needs to start, for the request’s user, or for a visitor who isn’t signed in.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleSessionModel(**data)[source]
The base class of the contract’s models: camelCase JSON, and no fields that a model doesn’t define.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleSidebar(**data)[source]
The urls of the sidebar’s links, reversed by the backend.
A link that the platform or the user doesn’t have is null, and the sidebar leaves it out.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleSignIn(**data)[source]
The ways to sign in or sign up that the sign-in pages offer.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleUser(**data)[source]
The signed-in user.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.api.web.session.contract.ConsoleWelcome(**data)[source]
The state of the welcome dialog for the user.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- smarter.apps.api.web.session.contract.RESPONSE_MODELS: tuple[type[BaseModel], ...] = (<class 'smarter.apps.api.web.session.contract.ConsoleSession'>,)
What the view sends.
(<class 'smarter.apps.api.web.session.contract.ConsoleSession'>, )
- smarter.apps.api.web.session.contract.SCHEMA_PATH = PosixPath('/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/apps/api/web/session/console-session.schema.json')
The committed JSON Schema of the contract.
- smarter.apps.api.web.session.contract.contract_schema()[source]
The contract’s JSON Schema (draft 2020-12): one definition, in
$defs, per model.It also has the models of the console’s account api,
smarter.apps.account.api.web.contract, so that the console generates every type it sends and receives from one schema.
- smarter.apps.api.web.session.contract.contract_schema_json()[source]
The contract’s JSON Schema, as the text of
console-session.schema.json.- Return type:
The web console’s session api, GET /api/web/session/.
It answers every request, signed in or not, with a ConsoleSession,
and sets the CSRF cookie, so that the single-page console can make its first POST, e.g. to sign in. See
smarter.apps.api.web.session.contract.
This endpoint is part of Smarter’s Django-React integration. See Django-React Integration.
- class smarter.apps.api.web.session.views.ConsoleSessionView(**kwargs)[source]
GET /api/web/session/: the console’s session, for any request.It is a GET, so that the console can call it before it has a CSRF token, and it sets the CSRF cookie. It is never cached: it describes the request’s own user.
- get(request, *args, **kwargs)[source]
Return the console’s session for the request’s user.
- Parameters:
request (
HttpRequest) – The request.- Return type:
- Returns:
A
ConsoleSession, as JSON.
- smarter.apps.api.web.session.views.LOGO_PATH = 'images/logo/smarter-crop.png'
The logo’s path on the project’s CDN.
- smarter.apps.api.web.session.views.branding()[source]
The platform’s branding, from
smarter_settings.- Return type:
- Returns:
The branding that the console shows.
- smarter.apps.api.web.session.views.console_account(user_profile)[source]
The account that the console acts for.
- Parameters:
user_profile (
UserProfile|None) – The selected profile, or None.- Return type:
- Returns:
The profile’s account, or None.
- Raises:
ValueError – when the account has no account number.
- smarter.apps.api.web.session.views.console_session(request)[source]
Everything the console needs to start, for the request’s user.
- Parameters:
request (
HttpRequest) – The request.- Return type:
- Returns:
The session. Without a signed-in user, its user, account, onboarding, welcome, badges and sidebar are None.
- smarter.apps.api.web.session.views.console_user(user, user_profile)[source]
The signed-in user, as the console shows them.
- Parameters:
user (
User) – The signed-in user.user_profile (
UserProfile|None) – Their selected profile, or None.
- Return type:
- Returns:
Who they are, their avatar, and how many accounts they belong to.
- smarter.apps.api.web.session.views.cookies()[source]
The names and domain of Django’s cookies.
- Return type:
- Returns:
The CSRF and session cookie names, and their domain.
- smarter.apps.api.web.session.views.flags(user)[source]
The console’s optional features, for this user.
- Parameters:
- Return type:
- Returns:
Which optional pages and widgets are on. The terminal is on only for a superuser.
- smarter.apps.api.web.session.views.language()[source]
The session’s language, and every language the console offers.
- Return type:
- Returns:
The language state, as LocaleMiddleware chose it for this request.
- smarter.apps.api.web.session.views.sam_kinds()[source]
Every SAM kind, sorted by name, for the console’s docs pages.
- smarter.apps.api.web.session.views.selected_user_profile(user)[source]
The profile that the console acts as, chosen by
smarter.apps.account.middleware.SmarterUserProfileSelectionMiddleware.- Parameters:
user (
User) – The signed-in user.- Return type:
- Returns:
The profile, or None for a user who has none.
- smarter.apps.api.web.session.views.sidebar(user, console_flags)[source]
The sidebar’s links, for the user.
The urls are
smarter.apps.dashboard.context_processors.sidebar_context()’s, which is cached. A link that the platform or the user doesn’t have is None.- Parameters:
user (
User) – The signed-in user.console_flags (
ConsoleFlags) – The console’s optional features, for the user.
- Return type:
- Returns:
The links.
- smarter.apps.api.web.session.views.sign_in_options()[source]
The ways to sign in or sign up that the sign-in pages offer.
- Return type:
- Returns:
Which OAuth providers, sign-up, footer links and doodle are on.
- smarter.apps.api.web.session.views.welcome(request, user)[source]
The welcome dialog’s state for the user.
- Parameters:
request (
HttpRequest) – The request, whose session records whether the dialog was closed in this session.user (
User) – The signed-in user.
- Return type:
- Returns:
Whether the dialog shows at startup, and whether it opens by itself now.
The contract of the console’s account api, /api/web/account/: its request bodies and responses, as Pydantic models.
Signing in, signing out and activating an account answer with the new
ConsoleSession, so that the console needn’t ask again.
Signing up, asking for a new activation link and the password reset endpoints answer with an
AccountMessage. A refused request answers with an
AccountErrors: a message for the whole form, and one or more messages per field, which the
console shows beside the fields. The JSON is camelCase.
The models are part of the console’s schema, console-session.schema.json: see
smarter.apps.api.web.session.contract.contract_schema().
- class smarter.apps.account.api.web.contract.AccountErrors(**data)[source]
A request that was refused, with why.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.account.api.web.contract.AccountMessage(**data)[source]
A request that succeeded, with a message for the user.
- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.account.api.web.contract.ActivationResendRequest(**data)[source]
The body of
POST /api/web/account/activation-resend/.- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.account.api.web.contract.NewPasswordRequest(**data)[source]
The body of
POST /api/web/account/password-reset/<uidb64>/<token>/.- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.account.api.web.contract.PasswordResetRequest(**data)[source]
The body of
POST /api/web/account/password-reset-request/.- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- smarter.apps.account.api.web.contract.REQUEST_MODELS = (<class 'smarter.apps.account.api.web.contract.SignInRequest'>, <class 'smarter.apps.account.api.web.contract.SignUpRequest'>, <class 'smarter.apps.account.api.web.contract.ActivationResendRequest'>, <class 'smarter.apps.account.api.web.contract.PasswordResetRequest'>, <class 'smarter.apps.account.api.web.contract.NewPasswordRequest'>)
What the console sends.
( <class 'smarter.apps.account.api.web.contract.SignInRequest'>, <class 'smarter.apps.account.api.web.contract.SignUpRequest'>, <class 'smarter.apps.account.api.web.contract.ActivationResendRequest'>, <class 'smarter.apps.account.api.web.contract.PasswordResetRequest'>, <class 'smarter.apps.account.api.web.contract.NewPasswordRequest'>, )
- smarter.apps.account.api.web.contract.RESPONSE_MODELS = (<class 'smarter.apps.account.api.web.contract.AccountMessage'>, <class 'smarter.apps.account.api.web.contract.AccountErrors'>)
What the views send, besides the console session.
( <class 'smarter.apps.account.api.web.contract.AccountMessage'>, <class 'smarter.apps.account.api.web.contract.AccountErrors'>, )
- class smarter.apps.account.api.web.contract.SignInRequest(**data)[source]
The body of
POST /api/web/account/login/.- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class smarter.apps.account.api.web.contract.SignUpRequest(**data)[source]
The body of
POST /api/web/account/register/.- model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'json_schema_serialization_defaults_required': True, 'serialize_by_alias': True, 'validate_by_alias': True, 'validate_by_name': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
The console’s account api, /api/web/account/: signing in and out, signing up and activating an account,.
and resetting a password.
These replace what the server-rendered sign-in pages’ forms did, as JSON for the single-page console
(ADR-035). Every POST needs the CSRF token, which GET /api/web/session/ sets. Signing in, signing up and
asking for an activation or password reset link are limited per IP address by
SmarterCredentialsRateThrottle. The bodies and responses are the models
of smarter.apps.account.api.web.contract.
These endpoints are part of Smarter’s Django-React integration. See Django-React Integration.
- class smarter.apps.account.api.web.views.AccountApiView(**kwargs)[source]
The base class of the account api’s views: JSON bodies, and the credentials rate limit.
- read_body(request, model)[source]
The request’s body, as the endpoint’s model.
- Parameters:
request (
HttpRequest) – The request, whose body is JSON.model (
type[TypeVar(RequestModel, bound=ConsoleSessionModel)]) – The endpoint’s request model.
- Return type:
TypeVar(RequestModel, bound=ConsoleSessionModel)- Returns:
The body.
- Raises:
InvalidRequest – when the body isn’t JSON, or isn’t the model.
- throttle_credentials(request)[source]
Check the request against the credentials rate limit.
- Parameters:
request (
HttpRequest) – The request.- Return type:
- Returns:
A 429 response if the address has made too many attempts, otherwise None.
- class smarter.apps.account.api.web.views.ActivateApiView(**kwargs)[source]
POST /api/web/account/activate/<uidb64>/<token>/: activate an account with its emailed link, and sign in.The console serves the emailed link,
/account/activate/<uidb64>/<token>/, and calls this with its two parts. It isn’t rate limited: the token is the credential, and a guess can’t be checked faster than the password reset link’s.- post(request, *args, **kwargs)[source]
Activate the link’s user, sign them in, and answer with the new session.
- Parameters:
request (
HttpRequest) – The request.kwargs –
uidb64andtoken.
- Return type:
- Returns:
The new session, or 404, 403 or 400 for a link that can’t be used.
- class smarter.apps.account.api.web.views.ActivationResendApiView(**kwargs)[source]
POST /api/web/account/activation-resend/: email a new activation link.- post(request, *args, **kwargs)[source]
Email a new link to the address’s inactive user, if they may activate by email.
The answer is the same either way.
- Parameters:
request (
HttpRequest) – The request, whose body is anActivationResendRequest.- Return type:
- Returns:
200 with an
AccountMessage; 400 for an invalid address; 429; or 500 if the email can’t be rendered.
- exception smarter.apps.account.api.web.views.InvalidRequest[source]
A request whose body isn’t the JSON that its endpoint takes.
- class smarter.apps.account.api.web.views.PasswordResetApiView(**kwargs)[source]
/api/web/account/password-reset/<uidb64>/<token>/: check an emailed link, and set a new password.The console serves the emailed link,
/password-reset-link/<uidb64>/<token>/, and calls this with its two parts.- get(request, *args, **kwargs)[source]
Check that the link can be used, before the console asks for the new password.
- Parameters:
request (
HttpRequest) – The request.kwargs –
uidb64andtoken.
- Return type:
- Returns:
200, or 404, 403 or 400 for a link that can’t be used.
- post(request, *args, **kwargs)[source]
Set the link’s user’s new password.
- Parameters:
request (
HttpRequest) – The request, whose body is aNewPasswordRequest.kwargs –
uidb64andtoken.
- Return type:
- Returns:
200; 400 with the passwords’ errors; or 404, 403 or 400 for a link that can’t be used.
- class smarter.apps.account.api.web.views.PasswordResetRequestApiView(**kwargs)[source]
POST /api/web/account/password-reset-request/: email a password reset link.- post(request, *args, **kwargs)[source]
Email a link to the user who has the address, if any, and answer the same either way.
- Parameters:
request (
HttpRequest) – The request, whose body is aPasswordResetRequest.- Return type:
- Returns:
200 with an
AccountMessage; 400 for an invalid address; 429; or 500 if the email can’t be rendered.
- class smarter.apps.account.api.web.views.SignInApiView(**kwargs)[source]
POST /api/web/account/login/: sign in with an email address and password.- post(request, *args, **kwargs)[source]
Sign in, and answer with the new session.
An unknown address and a wrong password get the same answer, so that it doesn’t reveal which addresses have accounts.
- Parameters:
request (
HttpRequest) – The request, whose body is aSignInRequest.- Return type:
- Returns:
The new session; 400 with
AccountErrors; 403 for the right password of an account that isn’t activated yet; or 429.
- class smarter.apps.account.api.web.views.SignOutApiView(**kwargs)[source]
POST /api/web/account/logout/: sign out.- post(request, *args, **kwargs)[source]
Sign out, and answer with the visitor’s session.
- Parameters:
request (
HttpRequest) – The request.- Return type:
- Returns:
The session of a visitor who isn’t signed in.
- class smarter.apps.account.api.web.views.SignUpApiView(**kwargs)[source]
POST /api/web/account/register/: create an inactive user, and email them an activation link.It answers 404 while the
ENABLE_ACCOUNT_REGISTRATIONswitch is off, as the sign-up page does.- post(request, *args, **kwargs)[source]
Create the user, and email them a link to activate their account.
- Parameters:
request (
HttpRequest) – The request, whose body is aSignUpRequest.- Return type:
- Returns:
200 with an
AccountMessage; 400 with the email’s and password’s errors; 404 while sign-up is switched off; 429; or 500 if the email can’t be rendered.
- smarter.apps.account.api.web.views.email_errors(email)[source]
The messages of an email address that isn’t valid.
- smarter.apps.account.api.web.views.errors_response(detail, field_errors=None, status=HTTPStatus.BAD_REQUEST)[source]
The response to a refused request.
- Parameters:
- Return type:
- Returns:
An
AccountErrors, as JSON.
- smarter.apps.account.api.web.views.link_error_response(error)[source]
The response to an emailed link that can’t be used.
- Parameters:
error (
EmailLinkError) – Why.- Return type:
- Returns:
404, 403 or 400, with the reason.
- smarter.apps.account.api.web.views.message_response(detail)[source]
The response to a request that succeeded, with a message for the user.
- Parameters:
detail (
str) – What happened.- Return type:
- Returns:
An
AccountMessage, as JSON.
- smarter.apps.account.api.web.views.password_errors(password, user)[source]
The messages of a password that Django’s password validators refuse.
- smarter.apps.account.api.web.views.session_response(request)[source]
The console’s session after signing in, out or up.
- Parameters:
request (
HttpRequest) – The request, whose session changed.- Return type:
- Returns:
The new
ConsoleSession, as JSON.
- smarter.apps.account.api.web.views.throttled_response(wait)[source]
The response to a request over the credentials rate limit.
- Parameters:
wait (
int) – The seconds to wait before retrying.- Return type:
- Returns:
A 429 response, with a
Retry-Afterheader.
- smarter.apps.account.api.web.views.unknown_error_response()[source]
The response to a request that failed on the server, e.g. an email that couldn’t be rendered.
- Return type:
- Returns:
500, with a message for the user.
Signing in with an email address and password, and signing up, for the console’s sign-in pages and api.
The console’s account api, smarter.apps.account.api.web.views, signs users in through these functions,
which record each failure in the login audit.
- smarter.apps.account.sign_in.awaits_activation(email, password)[source]
Whether this email address and password are those of a user who hasn’t activated their account yet.
Only someone who knows the password is told, so the answer doesn’t reveal which addresses have accounts.
- smarter.apps.account.sign_in.email_is_taken(email)[source]
Whether another user already has this email address, in any case.
- smarter.apps.account.sign_in.sign_in_with_email(request, email, password)[source]
Sign in the user who has this email address and password, in the request’s session.
A failure is recorded in the login audit, with its reason: an unknown address, or the password failure of
smarter.apps.account.login_audit.password_failure(). The caller answers every failure alike, so that the response doesn’t reveal which addresses have accounts.- Parameters:
request (
HttpRequest) – The request, whose session the user is signed in to.email (
str) – The email address. An email address belongs to one user.password (
str) – The password.
- Return type:
- Returns:
The signed-in user, or None.
- smarter.apps.account.sign_in.sign_up(request, email, password)[source]
Create an inactive user whose username and email address are
email, and email them an activation link.The user can sign in once they follow the link, which proves that the address is theirs. See
smarter.apps.account.activation. The caller checks first that the address is free and that the password is acceptable.- Parameters:
request (
HttpRequest) – The request, for the link’s host and the email’s template context.email (
str) – The email address, which is also the username.password (
str) – The password.
- Return type:
- Returns:
The new, inactive user.
- Raises:
RuntimeError – when the email’s template can’t be rendered.
Account activation: a user who signs up with an email address and a password is inactive until they follow the.
link that the platform emails them, which proves that the address is theirs.
The link is /account/activate/<uidb64>/<token>/: see smarter.apps.account.email_links. The console
serves its page, which activates the user and signs them in through the account api,
smarter.apps.account.api.web.views. Signing in uses the link, so it can’t be used twice.
Users that social sign-in creates are inactive too, but are activated by an administrator, never by email:
self-service activation is only for those who signed up with a password, while the
ENABLE_ACCOUNT_REGISTRATION switch allowed it. See SOCIAL_AUTH_CREATE_USERS in settings/base.py.
- smarter.apps.account.activation.ACCOUNT_ACTIVATE_LINK_NAME = 'account:account_activate'
The url name of the link, which
smarter.apps.account.urlsserves at/account/activate/<uidb64>/<token>/.
- smarter.apps.account.activation.EMAIL_TEMPLATE_PATH = 'account/authentication/email/account-activation.html'
The email’s template.
- smarter.apps.account.activation.PASSWORD_BACKEND = 'django.contrib.auth.backends.ModelBackend'
The authentication backend of a user who signed up with a password, which the activation signs them in with.
- smarter.apps.account.activation.activate(request, uidb64, token)[source]
Activate the user of an emailed link, and sign them in.
Signing in changes the user’s last sign-in, which the link’s token hashes, so the link can’t be used again.
- Parameters:
request (
HttpRequest) – The request, whose session the user is signed in to.uidb64 (
str) – The link’s encoded user id.token (
str) – The link’s token.
- Return type:
- Returns:
The active, signed-in user.
- Raises:
EmailLinkError – when the link is unknown, malformed, used or expired.
- smarter.apps.account.activation.activation_link(request, user)[source]
The absolute url of a new activation link for the user.
- Parameters:
request (
HttpRequest) – The request, for the link’s host and protocol.user (
User) – The user.
- Return type:
- Returns:
The link.
- smarter.apps.account.activation.can_activate_by_email(user)[source]
Whether a user may activate their own account with an emailed link.
- smarter.apps.account.activation.resend_activation_email(request, email)[source]
Email a new activation link to the user who has this address, if they may activate by email.
The caller answers the same either way, so that the response doesn’t reveal which addresses have accounts.
- Parameters:
request (
HttpRequest) – The request.email (
str) – The email address.
- Return type:
- Returns:
True if an email was sent.
- Raises:
RuntimeError – when the email’s template can’t be rendered.
- smarter.apps.account.activation.send_activation_email(request, user)[source]
Email the user a link to activate their account.
- Parameters:
request (
HttpRequest) – The request, for the link’s host and the email’s template context.user (
User) – The inactive user.
- Raises:
RuntimeError – when the email’s template can’t be rendered.
- Return type:
Password reset links: making one, emailing it, and reading it back.
A link is /password-reset-link/<uidb64>/<token>/, which expires: see smarter.apps.account.email_links.
The console serves the link’s page, and its account api, smarter.apps.account.api.web.views, uses these
functions. Emails that were sent before the console served it keep working: the link’s path is the same.
- smarter.apps.account.password_reset.EMAIL_TEMPLATE_PATH = 'account/authentication/email/password-reset.html'
The email’s template.
- smarter.apps.account.password_reset.PASSWORD_RESET_LINK_NAME = 'password_reset_link'
The url name of the link, which
smarter.urls.consoleserves at/password-reset-link/<uidb64>/<token>/.
- smarter.apps.account.password_reset.password_reset_link(request, user)[source]
The absolute url of a new password reset link for the user.
- Parameters:
request (
HttpRequest) – The request, for the link’s host and protocol.user (
User) – The user.
- Return type:
- Returns:
The link.
- Raises:
SmarterValueError – when
useris not a User.
- smarter.apps.account.password_reset.send_password_reset_email(request, email)[source]
Email a password reset link to the user who has this address, if there is one.
The caller answers the same either way, so that the response doesn’t reveal which addresses have accounts.
- Parameters:
request (
HttpRequest) – The request, for the link’s host and the email’s template context.email (
str) – The email address.
- Return type:
- Returns:
True if an email was sent, False if no user has the address.
- Raises:
RuntimeError – when the email’s template can’t be rendered.
- smarter.apps.account.password_reset.user_from_reset_link(uidb64, token)[source]
The user of a password reset link, if the link is valid and hasn’t expired.
- Parameters:
- Return type:
- Returns:
The user.
- Raises:
EmailLinkError – when the link is unknown, malformed or expired.
The links that the platform emails to a user: making one, and reading one back.
A link is /<path>/<uidb64>/<token>/: the user’s encoded id and a token that expires, made by
ExpiringTokenGenerator. The token hashes the user’s password
and last sign-in, so a link stops working once its user changes their password or signs in. Password
reset links (smarter.apps.account.password_reset) and account activation links
(smarter.apps.account.activation) are both made and read here.
- exception smarter.apps.account.email_links.EmailLinkError(message, status)[source]
An emailed link that can’t be used.
- Parameters:
message (
str) – Why, for the user.status (
HTTPStatus) – The http status that answers it: 404 for an unknown user, 403 for an expired link, 400 for a malformed or used one.
- smarter.apps.account.email_links.email_link(request, user, url_name)[source]
The absolute url of a new link for the user.
- Parameters:
request (
HttpRequest) – The request, for the link’s host and protocol.user (
User) – The user.url_name (
str) – The name of the link’s url, whose kwargs areuidb64andtoken.
- Return type:
- Returns:
The link.
- Raises:
SmarterValueError – when
useris not a User.
- smarter.apps.account.email_links.render_email(request, template_path, context)[source]
An email’s html, rendered from its template, without comments and minified.
- Parameters:
- Return type:
- Returns:
The html.
- Raises:
RuntimeError – when the template can’t be rendered.
- smarter.apps.account.email_links.user_from_email_link(uidb64, token)[source]
The user of an emailed link, if the link is valid and hasn’t expired.
- Parameters:
- Return type:
- Returns:
The user.
- Raises:
EmailLinkError – when the link is unknown, malformed, used or expired.