Authentication

Feather signs people in without passwords, in one of two ways:

Google. The user signs in with their Google account. You need OAuth credentials from a Google Cloud project.
Email. The user types their address and gets a link that signs them in. You need no Google Cloud project, only a way to send email.

Either way there is no password to store, and one flow covers both sign-up and sign-in: Feather creates the account the first time someone arrives. The approval workflows, roles and permissions below work the same for both. Choose with SIGN_IN_METHOD in config.py, or with feather new --sign-in email.

Setup: Google

Create OAuth credentials

In the Google Cloud Console.

Add the redirect URI

http://localhost:5173/auth/google/callback for development, or your production URL.

Add credentials to .env

.env

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# Session settings (optional)
SESSION_LIFETIME_DAYS=7        # default: 7
REMEMBER_COOKIE_DAYS=365       # default: 365
SESSION_PROTECTION=basic       # None, basic, strong

Create your admin user

python seeds.py

Setup: email

Choose email sign-in

feather new --sign-in email sets it for a new app. In an existing one, set it in config.py:

config.py

SIGN_IN_METHOD = os.environ.get("SIGN_IN_METHOD", "email")

Give it a way to send the email

Feather uses the first of these that is set:

Setting	What sends the email
`SIGN_IN_RELAY_URL` and `SIGN_IN_RELAY_TOKEN`	A relay run by your host. Appentic sets both on every Feather project, so there is nothing to do.
`RESEND_API_KEY`	Resend, from `RESEND_FROM_EMAIL`.
Neither	Nothing. The code is written to the log, which is what you want in development.

Create your admin user

python seeds.py

Then sign in with the admin address from seeds.py.

/auth/email/login asks for an address and emails a six-digit code. The page asks for the code whether or not the address has an account, so the form can’t be used to find out who does.
The code page has a box per digit. Typing the last digit, pasting the code, or letting a phone fill it in from the email signs the person in straight away, with no button to press. Without JavaScript it’s one field and a Sign in button.
New addresses are handled exactly as a first Google sign-in would be: created, and approved or held for approval.

A code works only in the browser that asked for it. That browser’s session holds a keyed hash of the code (never the code itself), the address and the expiry, so someone who sees or is forwarded the email has nowhere to use it. That is the point of a code over a link, which signs in whoever opens it. A code works once, expires after SIGN_IN_CODE_MINUTES (15), and stops working after five wrong tries; Send a new code replaces it. The tries and “works once” are counted in the cache, so with several workers configure Redis (REDIS_URL) to make them hold across all of them. To change how the pages look, copy feather/templates/auth/email_sign_in.html to templates/auth/email_sign_in.html in your app.

Routes

Route	Description
`/auth/google/login`	Start Google sign-in
`/auth/google/callback`	Google’s callback, handled for you
`/auth/email/login`	Ask for an address and email a sign-in code
`/auth/email/verify`	Sign in with the code (POST)
`/auth/email/resend`	Email a new code to the same address (POST)
`/auth/logout`	End session

Only the routes for your SIGN_IN_METHOD answer; the others return 404. Pages behind @auth_required send signed-out visitors to the right one.

<a href="{{ url_for('email_auth.login') }}">Sign in</a>   {# or google_auth.login #}
<form method="post" action="/auth/logout">
  <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
  <button type="submit">Sign out</button>
</form>

Approval workflows

In a single-tenant app, the address in ADMIN_EMAIL (in config.py, filled in from feather new --admin-email) is an active admin from its first sign-in, so the app’s owner is never held for approval. Everyone else follows the rules below. New users can be approved automatically or held for admin review.

Workflow	CLI option	Best for
Manual approval (default)	Auto-approve new user signups? No	Internal tools, B2B apps, invite-only
Auto-approve	Auto-approve new user signups? Yes	Consumer apps, open registration

Manual approval creates users in a suspended state. They see a pending-approval page until an admin approves them in the admin panel. This keeps drive-by signups out and leaves you in control of who has access. Auto-approve activates users on first login. Choosing it during scaffolding sets AUTO_APPROVE_USERS = True in config.py, and the framework handles the rest. There are no callback files or environment variables to add.

To switch an existing app to auto-approve, add AUTO_APPROVE_USERS = True to config.py.

Status pages

State	Redirect	Description
Pending	`/account/pending`	New user awaiting admin approval
Suspended	`/account/suspended`	Previously approved, now deactivated

Both pages are scaffolded with a message and a logout button, and use @login_only so users stay authenticated while they read them. Edit the templates in templates/pages/account/ to match your branding.

Decorators

from feather import auth_required, admin_required, role_required, login_only
from feather.auth import permission_required, platform_admin_required

@api.get('/me')
@auth_required                    # any authenticated, approved user
def get_profile():
    return {'user': current_user.to_dict()}

@page.get('/account/pending')
@login_only                       # authenticated but may be pending or suspended
def account_pending():
    return render_template('pages/account/pending.html')

@api.delete('/users/<id>')
@admin_required                   # tenant admin (role="admin")
def delete_user(id):
    pass

@api.post('/articles')
@role_required('editor')          # specific role, admin inherits all
def create_article():
    pass

@api.post('/tenants')
@platform_admin_required          # cross-tenant operations
def create_tenant():
    pass

Which one to use

Decorator	Use when
`@auth_required`	Any logged-in, approved user
`@login_only`	Authenticated but possibly pending or suspended, as on status pages

@login_only does not check that the account is active. Use it only for the pending and suspended pages. On any other route a suspended account keeps working, so feather check reports it on API routes and on routes that change data as login-only-action.

Roles

These defaults suit most apps, and you can add, remove or rename them.

Role	Purpose	Inherits
`user`	Basic access, the default for new users	none
`editor`	Content creation	`user`
`moderator`	Content moderation	`user`
`admin`	Tenant administration	all roles

Roles inherit permissions, so @role_required('editor') admits editors and admins. To customize, edit the hierarchy in feather/auth/roles.py:

ROLE_INHERITS = {
    "admin": {"admin", "editor", "moderator", "reviewer", "user"},
    "editor": {"editor", "user"},
    "moderator": {"moderator", "user"},
    "reviewer": {"reviewer", "user"},   # new role
    "user": {"user"},
}

Then use @role_required('reviewer'). The User model’s role field is a plain string, so adding a role needs no migration.

Permissions

Access control by action, mapped onto roles.

Permission	Who has it	Use case
`resources.read`	all roles	View data
`resources.create`	editor, admin	Create content
`resources.update`	editor, admin	Edit content
`resources.manage`	moderator, admin	Moderation actions
`resources.delete`	admin only	Delete content
`*`	admin only	All permissions

from feather.auth import permission_required

@api.get('/articles')
@permission_required('resources.read')      # all authenticated users
def list_articles():
    pass

@api.delete('/articles/<id>')
@permission_required('resources.delete')    # admins only
def delete_article(id):
    pass

Permissions live in feather/auth/permissions.py and extend the same way roles do.

Seeds

seeds.py populates initial data. The scaffolded version creates your admin user with the email you gave during feather new. Extend it for your own data:

seeds.py

def seed():
    # admin user (scaffolded)
    admin = User(email=ADMIN_EMAIL, role="admin", active=True)
    db.session.add(admin)

    # your seed data
    default_categories = ["General", "Support", "Billing"]
    for name in default_categories:
        db.session.add(Category(name=name))

    db.session.commit()

Run it with python seeds.py or feather db seed. The scaffolded seed is idempotent, updating existing users rather than duplicating them.

Callbacks

For apps that need account setup after OAuth.

.env

FEATHER_POST_LOGIN_CALLBACK=myapp.auth:handle_login

myapp/auth.py

def handle_login(user, token):
    """Called after OAuth login with user and token.

    Returns:
        Redirect URL string, or None for default behavior
    """
    if not user.account_id:
        return '/onboarding/select-plan'
    return None

Use it to create Account or Membership records, assign tenants to users with public email addresses, or drive an onboarding flow.

Pre-register callback

Block new registrations before the account is created. This runs during signup for new users only. Existing users logging in are unaffected.

.env

FEATHER_PRE_REGISTER_CALLBACK=myapp.auth:check_registration

myapp/auth.py

from flask import request

def check_registration():
    """Returns an error message to block, or None to allow."""
    ip = request.headers.get("X-Real-IP", request.remote_addr)
    if is_blocked(ip):
        return "Registration is not available from your location."
    return None

A returned string blocks registration, shows the message as a toast error, and creates no user record. None lets registration proceed. Errors raised inside the callback are logged but don’t block signups.

Get started

Tutorial: build a Kanban app

Building the UI

Backend

Features

Tooling

Testing

Deployment

Setup: Google

Setup: email

Routes

Approval workflows

Status pages

Decorators

Which one to use

Roles

Permissions

Seeds

Callbacks

​Setup: Google

​Setup: email

​How a sign-in code works

​Routes

​Approval workflows

​Status pages

​Decorators

​Which one to use

​Roles

​Permissions

​Seeds

​Callbacks

Setup: Google

Setup: email

How a sign-in code works

Routes

Approval workflows

Status pages

Decorators

Which one to use

Roles

Permissions

Seeds

Callbacks