Accounts, approval and API keys

A developer account on ALYT is separate from a household account and separate from staff. Developers sign up in the developer portal, verify their email, and receive their own sandbox tenant plus a developer API key. That key is the way they authenticate to the API. Approval is not part of sandbox access: a alyt_dev_ key is issued immediately after signup, while alyt_live_ keys are issued only after approval for a published connector the developer owns. The platform keeps the home working even when the cloud is down, so a developer’s sandbox and its local behavior remain useful without depending on cloud availability.

Account model

A developer is a fourth kind of account, not a fifth role. The developer side has its own identity and its own sessions, and it does not reuse a platform or household account. The same email address can belong to both a household account and a developer account, with separate passwords and separate sessions.

Developer accounts carry these fields:

• email, unique among developers only
• passwordHash
• emailVerifiedAt
• passwordChangedAt

The developer portal also uses two related records:

• DeveloperSession for rotating refresh tokens
• DeveloperToken for one-time verify and reset links

A developer session is not a platform session, and a platform session is not a developer session. The developer sign-in flow starts on the developer gateway. If a developer is also staff, the portal can fall back to the staff sign-in path after a 401.

Signup and approval

Signup is self-service. A developer creates an account, verifies their email, and gets access to their own sandbox tenant without waiting for a human. This is safe because the sandbox is isolated and does not reach a real household.

Approval enters only when something touches real consequence:

Stage	Human approval?	Result
Developer signup	No	Sandbox tenant and alyt_dev_ key
Use ALYT local AI	Yes	Access to the local AI gate
Publish an integration	Yes	alyt_live_ key for a published definition

A alyt_live_ key is only issued for a published definition the developer owns. It is narrowed to that definition’s own integrations and does not permit writes in the publication path.

Authentication

Developers sign in with POST /developers/auth/login. The response includes:

• an access JWT for the developer side
• a rotating refresh token

The access token is valid for 15 minutes. The refresh token lasts 30 days, rotates on every refresh, and is revoked on logout and on any password change.

The developer portal also supports password recovery:

• POST /developers/auth/forgot-password always returns the same response
• the reset link lasts one hour
• resetting the password sets the new hash, marks the email verified, and ends every session

Invited developers start with an unusable password hash and set a password through the same reset flow.

Two-factor sign-in

Two-factor sign-in uses TOTP only. SMS is not supported. It is off by default and a developer turns it on from the account page.

The flow is:

1. POST /developers/auth/mfa/setup returns a candidate secret as QR and text
2. POST /developers/auth/mfa/enable confirms the secret with one code
3. The response includes eight recovery codes, shown once
4. POST /developers/auth/login rejects a correct password without a second factor with 401 totp required
5. POST /developers/auth/mfa/disable needs the password and a code, then clears the secret and ends every other session

Recovery codes are one-time use. The audit log records developer.mfa_enabled, developer.mfa_disabled, and developer.recovery_code_used.

API keys

API keys are hashed at rest and shown only once, at creation. There is no reveal path. Keys are prefixed and identifiable, and the public identifier can appear in the console, audit log, and usage counters without exposing the secret.

The two key kinds are distinct:

Key	Reach	Issued	Data
alyt_dev_…	Developer’s own sandbox tenant and virtual devices	At signup, immediately	The developer’s own data
alyt_live_…	Real tenants that installed the developer’s integration	After approval	Other people’s homes

Keys are scoped, rotatable without downtime, and revocable instantly. During rotation, two live keys may exist at once. Revocation is a first-class event and belongs in the audit log.

Tracing and usage

All key activity needs to be traced, but different questions need different records.

Question	Answered by
Who did this, and when?	Audit log
How much has this key used?	Per-key usage counters
What did this request do?	Request-level tracing

The key id belongs in all of them. The key secret belongs in none of them.

Usage counting happens at the gateway, where the key is already resolved. It does not belong in individual services.

What a developer sees

A developer sees their own account, their own sandbox tenant, and their own keys. They do not see the shadow platform user, implementation details, or internal storage choices. They can manage sign-in, recovery, MFA, and key rotation from the portal, and they can use the sandbox key right away without waiting for approval.

A live key is different: it exists only after review, only for a published connector the developer owns, and only for the tenants that installed it. That is the point where ALYT treats the request as reaching other people’s homes.

Developer-facing rules

• Developer and household identities are separate.
• Email verification happens before a key is minted.
• alyt_dev_… keys are immediate and sandbox-only.
• alyt_live_… keys require approval.
• Keys are hashed, scoped, revocable, and visible only once.
• MFA uses TOTP and recovery codes.
• Audit logging covers sign-in events, key issue and revoke events, approval events, and MFA events.
• The house keeps working when the cloud is down; developer sandbox access follows the same local-first expectation wherever the platform is local.