Reference

Reference

Everything you can manage in Accounts, plus the HTTP surface products and the CLI use to authenticate. Accounts is served from account.destesi.io; its API is served from api.account.destesi.io.

Finding your way around

The account sidebar is your map. These are the top-level destinations, exactly as they’re labelled in the UI:

Sidebar item	What’s there
Home	Your profile summary and active sessions at a glance.
Personal info	Name, email, phone, and profile picture.
Data & privacy	Sign-in activity, connected products, and email preferences.
Security	Two-factor authentication and the list of active sessions.
Workspace	Your workspaces, members, roles, and invites.
Payments & subscriptions	Payment methods, subscriptions, and product credits.
Settings	A small hub linking to API tokens and Personal info.

Note

Settings here refers to the Settings hub at /me/settings — a short index page whose only links are API tokens and Personal info. Most things people call “settings” (your profile, security, workspace) are their own top-level sidebar items, not pages nested under Settings.

Account profile

Manage your personal details under Personal info in the sidebar.

Field	Notes
name	Display name.
phone	Optional contact phone.
avatar_url	Optional avatar image URL.
email	Set at signup; used to sign in.

Editable fields: name, phone, avatar_url. Your email and password are managed through the sign-in and password-reset flows.

Passwords

• Minimum length: 12 characters.
• Forgot your password? Request a reset from the login page; a reset link is emailed to you. The link is single-use and time-limited.
• Resetting your password revokes your other sign-in sessions.

Two-factor authentication (2FA)

Turn on TOTP-based 2FA from Security in the sidebar:

1. Set up generates a secret and an otpauth:// URL — scan it with an authenticator app.
2. Activate by entering a current code. On activation you’re given one-time backup codes — store them somewhere safe.
3. With 2FA on, signing in returns a challenge instead of an immediate session; you complete it with a TOTP code or a backup code.
4. You can regenerate backup codes or disable 2FA later (both require a current code).

Workspaces

A workspace is the unit of collaboration; every product scopes its data to a workspace. Manage workspaces under Workspace in the sidebar.

Field	Notes
slug	URL-safe identifier, unique across Destesi.
name	Human-readable display name.
billing_email	Optional billing contact.

• A personal workspace is created automatically at signup.
• You can create additional workspaces; the slug must be unique (a clash returns slug_taken).
• Your active workspace is carried in your session and travels with you across products.
• A workspace’s access tier is tracked per product as an entitlement, not as a single workspace-wide plan field.

Members and roles

Invite teammates by email from the workspace settings. Roles:

Role	Capability
owner	Full control of the workspace.
admin	Manage members and workspace settings.
member	Standard access.

• Invites are sent by email with a one-time accept link that expires.
• You can change a member’s role or remove a member at any time.
• Invites can be issued at the admin or member role.

API tokens

Personal API tokens authenticate the CLI and server-to-server clients on your behalf. Manage them under Settings → API tokens (or the API tokens shortcut on the Personal info page). Treat tokens like passwords.

Field	Notes
name	1–80 characters. Required.
scope	read (read-only) or write (full read-write, the default).
expires_in_days	Optional, 1–730. Omit for a non-expiring token.
prefix	The visible, non-secret leading characters used to identify the token.
last_used_at	When the token was last seen.

Caution

The full token value is shown exactly once, at creation time. Copy it then — you can’t retrieve it again. If you lose it, revoke the token and mint a new one.

Revoking a token immediately stops clients using it from working.

Sessions

Under Security in the sidebar you can see every active session for your account — what kind it is, which product it belongs to, when it was last seen, and when it expires — and revoke any of them. The session you’re currently using is marked as current.

Data & privacy

The Data & privacy sidebar item gathers the read-only privacy view of your account: a Privacy checkup, your sign-in activity (which links to the session list under Security), the products connected to your account through single sign-on, and your email preferences.

Email preferences

The Email preferences card lists the kinds of email Destesi sends — security alerts, product updates, and marketing — and shows their current state. Security alerts are always sent.

Payments & subscriptions

Payments is where you subscribe to a product or a bundle, change plan, or cancel. Checkout, plan changes, and cancellation all run through Stripe’s hosted pages, so card details never reach Destesi — nothing is charged until you confirm there. If a bundle you’re buying overlaps something you already pay for, you’re shown the overlap before checkout.

Usage shows each product’s allowances and what your workspace has consumed against them.

Subscriptions apply to the workspace, so a plan bought by one member covers everyone in it. See Plans and billing for the pricing model and the bundles.

Single sign-on API

Products and the CLI talk to the Accounts API to authenticate. You won’t normally call these directly, but here is the surface.

Auth uses a host-only session_token cookie set on the Accounts origin. Your sign-in (master) session is long-lived; product sessions are short-lived and refresh silently against it.

Authentication

Method	Path	Purpose
POST	/v1/auth/signup	Create an account and a sign-in session.
POST	/v1/auth/login	Authenticate. Returns a 2FA challenge if 2FA is enabled.
POST	/v1/auth/2fa/verify	Complete a 2FA challenge with a TOTP or backup code.
POST	/v1/auth/logout	Revoke the current session and clear the cookie.
POST	/v1/auth/forgot-password	Request a password-reset email (always succeeds, to prevent email enumeration).
POST	/v1/auth/reset-password	Reset a password using an emailed token.
GET	/v1/auth/options	List which sign-in providers are configured.
GET	/v1/auth/oauth/{provider}/start	Begin a provider sign-in (e.g. Google, GitHub).
GET	/v1/auth/oauth/{provider}/callback	Provider redirect target.

Single sign-on handoff

Method	Path	Purpose
POST	/v1/auth/exchange	Mint a one-time, 60-second exchange token for a product (requires a sign-in session).
POST	/v1/auth/redeem	Consume an exchange token and mint a product session.
POST	/v1/auth/refresh	Silently extend a product session against the sign-in session.
POST	/v1/auth/validate	Check whether a session is valid (used by products on each request).

Product sessions are valid for one hour and are refreshed transparently — you never see an interruption.

Account and workspaces

Method	Path	Purpose
GET	/v1/me	Current user, workspaces, and active workspace.
PATCH	/v1/me	Update name, phone, avatar_url.
POST	/v1/me/active-workspace	Set your active workspace.
GET	/v1/me/products	Products available in the launcher.
GET / DELETE	/v1/me/sessions, /v1/me/sessions/{id}	List and revoke sessions.
POST / GET / DELETE	/v1/me/api-tokens, /v1/me/api-tokens/{id}	Create, list, and revoke API tokens.
GET / POST	/v1/workspaces	List or create workspaces.
GET / PATCH / DELETE	/v1/workspaces/{slug}	Read, update, or delete a workspace.
GET / POST	/v1/workspaces/{slug}/invites	List and create invites.
POST	/v1/workspaces/accept-invite	Accept an invite by token.
GET / PATCH / DELETE	/v1/workspaces/{slug}/members, /v1/workspaces/{slug}/members/{user_id}	List members, change roles, remove members.
GET	/v1/workspaces/{slug}/entitlements/{product_id}	Read a workspace’s entitlement for a product.

See Entitlements for how product access and tiers are tracked per workspace.

Health

Path	Purpose
GET /healthz	Liveness (process is up).
GET /readyz	Readiness (database reachable).
GET /metrics	Prometheus metrics.

Configuration (self-hosting)

If you run Accounts yourself, these are the environment variables it reads. The API binds to :9091 by default.

Variable	Purpose
IDENTITY_API_ADDR	Listen address (default :9091).
IDENTITY_DATABASE_URL	Postgres connection string.
DESTESI_REDIS_URL	Redis backend for the audit-event worker. Unset disables async audit writes.
IDENTITY_WEB_URL	Public origin of the Accounts web app; used to build links in reset-password emails.
IDENTITY_WEB_DIR	Path to the built Accounts web bundle to serve from the same origin (prod).
IDENTITY_WEB_DEV_ORIGIN	Origin allowed for credentialed CORS when the web app runs as a separate dev server.
IDENTITY_EMAIL_FROM / IDENTITY_GMAIL_DELEGATED_USER	Outbound email sender. An empty Gmail service-account key prints emails to stdout (dev).
IDENTITY_GMAIL_SERVICE_ACCOUNT_KEY	JSON key contents for Gmail-API delivery in production.
IDENTITY_OAUTH_REDIRECT_BASE_URL	Public origin where OAuth callbacks land.
IDENTITY_OAUTH_GOOGLE_CLIENT_ID / _CLIENT_SECRET	Google sign-in. Only registered when both are set.
IDENTITY_OAUTH_GITHUB_CLIENT_ID / _CLIENT_SECRET	GitHub sign-in. Only registered when both are set.
IDENTITY_SUPERADMIN_SEED_EMAIL / _PASSWORD	Optional dev-only bootstrap superadmin, created idempotently at boot. Leave empty in production.

Note

A sign-in provider only appears as an option when both its client ID and client secret are configured; otherwise its endpoints return 404. Third-party credentials for products (GitHub repos, social accounts, stock media, and so on) are not configured here — they’re connected once per workspace in Connect and fetched by products at call time.