App authentication
Two identities
Section titled “Two identities”| Identity | What it controls | How you use it |
|---|---|---|
| Platform account and agent key | Owned apps, deployment, user administration and dashboard | bfast login and management commands |
| App user and app session | Protected routes and records inside one app | App login, then Authorization: Bearer <access_token> |
The same email address can identify different users in different apps. Your platform login does not create an app user. Never send a platform key to an app’s business or auth endpoints.
Fresh apps use native auth in their own SQLite database. Password checks, session checks, current roles and business authorization stay local to that app. Platform accounts use the platform’s separate auth service. Existing shared-auth apps retain their selected backend.
Test without SMTP
Section titled “Test without SMTP”bfast users create --app my-counter --email tester@example.invalid \ --name "Test User" --verifiedbfast request --app my-counter --email tester@example.invalid --path /countersBoth commands prompt for the app password as needed. The owner verification flag is an explicit attestation. It does not prove inbox ownership. See user commands.
Public signup
Section titled “Public signup”Configure app SMTP first. Use the exact stored app origin for all paths.
The supported callback is <app origin>/__bf/auth/complete.
POST /__bf/auth/sign-up/emailContent-Type: application/jsonOrigin: https://amber-apex-a1b2c3.tr1.edge.backend.fast
{"name":"App user","email":"you@example.com","password":"<new app password>","callbackURL":"https://amber-apex-a1b2c3.tr1.edge.backend.fast/__bf/auth/complete"}Open the verification link from the user’s inbox. It returns a completion page. Missing mail configuration does not bypass verification. The platform sender does not automatically configure every customer’s app sender.
Log in
Section titled “Log in”POST /__bf/auth/loginContent-Type: application/jsonOrigin: https://amber-apex-a1b2c3.tr1.edge.backend.fast
{"email":"you@example.com","password":"<app password>"}The response includes access_token, token_type: "Bearer" and user details.
Treat the token as an opaque value. Native login does not return the legacy
expires_in field. Do not decode a token as a JWT or infer its format.
GET /countersAuthorization: Bearer <app access token>Cookie clients must send the exact app Origin on mutations. Native login sets a Secure, HttpOnly, host-only refresh cookie. General browser access from unrelated origins is not enabled. Use a server client or the registered app origin.
Refresh, logout and reset
Section titled “Refresh, logout and reset”| Action | Request |
|---|---|
| Refresh | POST /__bf/auth/refresh, JSON {}, current app bearer and session cookie |
| Logout | POST /__bf/auth/logout, JSON {}, current app bearer and session cookie |
| Request reset | POST /__bf/auth/request-password-reset, JSON email and the exact callbackURL |
Native refresh replaces the token and preserves its absolute one-hour deadline. It does not extend the session indefinitely. Log in again after expiry. Logout revokes that session. Password reset and owner account changes revoke applicable sessions. Store cookies securely; do not put tokens into URLs or persistent browser storage.
Use the Counter Python client for a complete
prompt-based example, or let bfast request handle one login/request/logout cycle.
Reusing app sessions is appropriate for real clients. Repeated CLI logins are not
a throughput benchmark.
Roles and ownership
Section titled “Roles and ownership”@auth none, @auth user, @auth admin and @auth user owns Model.field control
routes. Caller-supplied user/role headers grant no authority. The app checks the
current user and role in the business transaction. An app administrator receives
no platform or other-app privilege.
Fresh native apps have no commercial user-count cap or small global session cap. Separate operation budgets, one password task, bounded cleanup and disk headroom remain. Optional per-user controls can restrict sessions. These limits bound work; they do not promise unlimited capacity. See current limits.