Skip to content

App authentication

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.

Terminal window
bfast users create --app my-counter --email tester@example.invalid \
--name "Test User" --verified
bfast request --app my-counter --email tester@example.invalid --path /counters

Both 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.

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/email
Content-Type: application/json
Origin: 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.

POST /__bf/auth/login
Content-Type: application/json
Origin: 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 /counters
Authorization: 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.

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.

@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.