User & auth management

Updated July 2026

Dousen has two separate services, each with its own users, its own role enum, and its own JWTs: DousenControl, the cloud control plane that manages orgs and billing, and DousenCore, the studio instance an org's members actually sign into day to day (whether that instance runs on Dousen's cloud or on the studio's own hardware). This page is both a concept guide and a full reference for both. If you just want the endpoints, jump to the auth endpoint reference.

Two services, two role models

Roles on a studio instance

The entire web portal (/portal/* — project CRUD, conventions, validators, pipeline settings, users, changelists, assets, validation history, the health dashboard, the material-catalog viewer) is gated behind the web_portal license feature and, within that, an admin-only guard on every console page. Non-admin roles get a self-service account page instead of a 403.

The guard is a middleware, require_admin, layered over the whole console router; a non-admin who requests a console page is redirected, not rejected outright, since they still have a valid session and a landing page to go to. The JSON REST API is stricter: each admin-gated handler checks the role inline and returns a flat 403 instead of redirecting.

Creating and managing users

On a studio instance, an Admin manages users from the portal's Users page.

Create-user takes four fields — email, display name, password, and role (admin, producer, or artist):

HTTPPOST /portal/users HTTP/1.1
Content-Type: application/x-www-form-urlencoded

email=jane%40studio.com&display_name=Jane+Doe&password=…&role=artist

Creation checks the seat limit before inserting the row — the license's configured seat count, or 5 if no license is set at all.

Password reset & recovery

Two entry points share the same underlying mechanics — one self-service, one admin-triggered:

A reset token is a random value, SHA-256-hashed before storage, valid for 1 hour, capped at 5 use attempts, and rate-limited to 3 new requests per email per hour. A new password must be at least 8 characters. Both the self-service and admin-triggered paths always render a neutral response regardless of whether the account exists, so neither leaks which emails have accounts.

LDAP- and SSO-provisioned accounts are excluded from this flow entirely — they carry a non-parseable password-hash sentinel instead of a real hash, so there is no local password to reset; those users authenticate through their directory or the cloud exchange every time.

Sign-in methods

A user who belongs to more than one cloud org sees a studio picker before landing in a specific instance, both during interactive login and during the OAuth flow.

Sessions, tokens & single-device enforcement

On a DousenCore instance, the access token is a short-lived JWT (15 minutes) and the refresh token is a longer-lived opaque value (30 days) that rotates on every use — refreshing revokes the old refresh token and issues a fresh pair. DousenDesktop's client auto-refreshes on a 401 without the user noticing.

Single-device enforcement: a refresh token can carry a device_id. If a refresh or heartbeat request arrives with a different device_id than the one stored for that session, the server answers 409 Conflict with "session active on another device" and the app surfaces that to the user — signing in elsewhere effectively ends the other session's ability to refresh.

Cloud orgs & studios (DousenControl)

Org membership is managed entirely on DousenControl, separately from any DousenCore instance.

People are added by invite, not by an admin setting a password:

An invite is seat-checked before it's created, expires after 7 days, and can only be admin or member (an org's owner is never assigned by invite). The invitee — not the admin — sets their own password when accepting, and it must be at least 8 characters; a second, concurrent accept on the same seat-limited org can't oversubscribe it, since the seat check and the insert happen atomically.

These are the seat counts a new subscription starts with; Stripe can override the number later from the actual purchased quantity. Each DousenCore instance heartbeats its current user count back to DousenControl daily. If that count exceeds the seat limit for three consecutive heartbeats, the org is suspended (403 on further heartbeats) and the owner is emailed; a later heartbeat back under the limit auto-reactivates it. A subscription that's merely past_due on payment is never suspended for that reason alone — only a real seat overage triggers it.

Worked examples

Self-hosted: adding a new artist

1. Admin opens Users.

   In the portal, Users lists everyone on the instance along with the seat count used out of the license limit.

2. Admin creates the account.

   Email, display name, a password the admin picks, and role artist. The seat check runs before the row is inserted — past the limit, creation is refused with the current/limit counts in the error.

3. The admin shares the password out of band (chat, in person — not email, since there's no invite mechanism to do that safely here) or sends a reset link instead, so the artist sets their own password on first use.
4. The artist signs in from DousenDesktop or the portal, lands on their own self-service account page (not the console), and can change their password or review active sessions any time.

Cloud: inviting a teammate

1. Owner or admin sends an invite from the org dashboard — an email plus a role (admin or member). This fails up front if the org is already at its seat limit.
2. The invitee gets an email with a 7-day link and clicks it to accept, choosing their own password (8+ characters) at that point — the org admin never sees or sets it.
3. They sign in to the studio via browser OAuth or the login form; on first arrival at a specific DousenCore instance, the SSO exchange auto-provisions their account there, mapping their cloud role to instance Admin or Artist.

Auth endpoint reference

DousenCore (per studio instance)

DousenControl (cloud)