Who can sign in

The four grants

The runtime gate — the same code path /api/oauth/token and SAML issuance both run — admits somebody if any of these says yes. Each one is a decision a person made.

Roles are the union of every grant that applied. A role slug is the exact value that appears in the roles claim of the ID and access tokens, so your application reads it directly — no lookup call.

Assigning people and groups

# one person, with a role
authfu apps assign app_1 --user teammate@example.com --role editor

# a whole group
authfu groups create "Finance"
authfu groups members add Finance teammate@example.com
authfu apps assign app_1 --group Finance --role viewer

# who can reach it now?
authfu apps assignments app_1

Assigning an address that has no Authfu account yet is not a failure — it comes back as pending, and the roles are waiting at that person’s first sign-in. Unassigning removes both the access and the launcher tile immediately; nothing is cached.

Access policies

A policy is the alternative to naming people one at a time. It has two independent axes:

• Allowed domains — only these email domains may sign in. This restricts your own app and grants you nothing over anybody, so it needs no domain verification.
• Require an invite — only people holding an invitation may sign in.

You can set both at once. A policy that has been deliberately set to restrict nobody admits every signed-in account, which remains supported — but Authfu will not advertise such an app with a launcher tile. An open door is not an invitation.

Why somebody was refused

Two refusals look identical from outside and have nothing in common as problems. Nobody granted them anything is a setup gap you close with one command. Somebody switched them off — blocked on the app, suspended in the organization — is a decision to reverse. Authfu tells you which, rather than making you infer it from the absence of a tile.

$ authfu access explain stranger@example.com --app app_1
DENIED    stranger@example.com -> Fite Camp
  cause     configuration — nothing grants them access to this app
  reason    not_configured (applies to everybody on this app)
  detail    The app has no access policy, so nothing is admitted by policy.
            Access to it comes from an assignment or from owning it.

Every refusal carries a kind: configuration, authorization, or preference (the person hid their own tile — their access is unchanged). The answer also reports the door and the launcher tile separately, and names the disagreement when they differ.

Over the API

GET    /api/v1/apps/{clientId}/assignments      # groups, people, pending
POST   /api/v1/apps/{clientId}/assignments      # {"group"|"email", "roles"?: []}
DELETE /api/v1/apps/{clientId}/assignments      # {"group"|"email"}
GET    /api/v1/apps/{clientId}/access/explain?email=…

These need their own key scopes — assignments:read, assignments:write, groups:read, groups:write — which are separate from apps:write on purpose, so a key that can create applications cannot by itself grant people access to them. Ask for them at authfu login.