API Tokens and Device Login

​

Enable

a, err := theauth.New(theauth.Config{
    Storage: store, // must implement APITokenStorage (memory does)
    BaseURL: "https://app.example.com",
    APITokens: &theauth.APITokensConfig{
        Abilities: []string{"read", "write", "deploy"},
        UserAbilities: func(ctx context.Context, u *theauth.User) ([]string, error) {
            return abilitiesFor(u), nil // your role model
        },
        Device: &theauth.DeviceConfig{
            VerificationURI:  "https://app.example.com/device",
            DefaultAbilities: []string{"read"},
        },
    },
})

​

Model

• A token is <prefix>_<43 random chars>. The secret is returned once. Only its SHA-256 is stored, plus a short hint for display.
• Abilities are strings you define. root is reserved, implies every ability, and cannot be combined with others.
• Every token expires. The default lifetime is 90 days, capped by MaxTTL (365 days).
• The owner is a user or a service account. A service account is an ID with no user row, created by an admin minting a token with service_account: true.
• Abilities are checked fresh on every request: a token’s effective abilities are its stored abilities intersected with what the owner currently holds. Demoting a user narrows their existing tokens at once.
• A token stops working when its owner row is deleted or OwnerActive reports false. Call RevokeOwnerAPITokens when you delete a user or retire a service account.

​

Protect routes

r.With(a.RequireAbility("deploy")).Post("/deploy", handler)

​

HTTP routes

​

Device grant

1. The CLI calls POST /auth/device/code (client_name, scope as space separated abilities) and shows the user_code and verification_uri.
2. A signed-in user posts the code to POST /auth/device/approve with action of info, approve or deny, optionally narrowing abilities.
3. The CLI polls POST /auth/device/token with the device grant type until it gets access_token.

• Polling faster than the interval returns slow_down and widens the interval by 5 seconds.
• Redeem is an atomic claim: of any number of concurrent polls, exactly one mints a token.
• The minted token expires (DeviceConfig.TokenTTL, default 30 days) and its abilities are the requested set capped to the approver’s current abilities. root is granted only when requested and the approver holds it, otherwise approval fails with 403.
• Wrong user codes count against a per-approver and per-IP budget (5 per 15 minutes), after which approval returns 429.
• Show the requester IP and user agent from action: info on your approval page.

​

Approve from a pending list

• GET /auth/device/requests returns {"requests": [...]} with id, clientName, requestedAbilities, requesterIp, requesterUserAgent, createdAt and expiresAt for each pending, unexpired request, newest first. It never includes the device code, its hash, or the user code. Show the IP and user agent so people recognize their own request.
• POST /auth/device/requests/{id}/approve and POST /auth/device/requests/{id}/deny decide by request ID with the same rules as the code route: atomic, abilities capped to the approver’s, root only when requested and held. Approve accepts an optional abilities list to narrow. A device.approved or device.denied audit event is recorded.

​

Custom storage