splent_feature_apikeys

Developer API tokens for a SPLENT product, and the only place in a product where a password is exchanged for a credential a machine can carry.

It owns tokens and nothing else. It does not know what the tokens are used for, since the features that guard routes with a token register the scopes they check. It never touches the auth feature either, because credentials are checked through the AuthenticationService that auth already registers.

The model

ApiToken belongs to one user and keeps:

A plaintext token looks like splent_<64 hex characters>. The splent_ label makes a leaked token greppable; the prefix makes verification a single indexed lookup instead of a table scan.

Scopes

A scope belongs to the feature that checks it. That feature registers it from its own init_feature, with a label the token form shows beside the checkbox.

from flask_babel import lazy_gettext as _l
from splent_io.splent_feature_apikeys.scopes import register_api_scope

def init_feature(app):
    register_api_scope("read_reports", _l("Read the published reports"))
    register_api_scope(
        "write_reports", _l("Publish and withdraw reports"), default=False
    )

This feature registers read_spl and write_spl itself, the scopes of the SPLENT command line.

register_api_scope(name, label=None, order=100, *, default=True, writes=None)

Registering a name again replaces its label, order, default and writes.

A scope that lets a token change things (upload, publish, delete) is registered with default=False. Then a token gets it only when its creator ticks it on the form or names it in the request, never because nobody chose.

The registry and default= arrive in the same release, so an apikeys that has register_api_scope takes the argument. A feature that also has to run with an older apikeys only guards the import, catching ImportError and AttributeError, and registers nothing when the registry is missing.

def init_feature(app):
    try:
        from splent_io.splent_feature_apikeys.scopes import register_api_scope
    except (ImportError, AttributeError):
        # An apikeys older than its scope registry: say so and register
        # nothing, so the product still starts.
        logger.warning("apikeys has no scope registry")
        return
    register_api_scope(
        "write_reports", _l("Publish and withdraw reports"), default=False
    )

What a product hands out is decided at request time by two settings.

A product that offers write scopes should set APIKEYS_DEFAULT_SCOPES to the read scopes its clients need. Left empty, the default comes from how each feature registered its scopes, and a write scope registered without default=False is a default like any other. A scope the setting names is a default even when it was registered with default=False, so the product has the last word.

# A product whose tokens are for its own API, not for the command line
[tool.splent.config]
APIKEYS_SCOPES = ["read_reports", "write_reports"]
APIKEYS_DEFAULT_SCOPES = ["read_reports"]

When no offered scope is a default, a caller that does not choose is refused with 400 and asked to name the scopes the token needs.

The token form, POST /api/v1/auth/tokens and ApiTokenService.mint all read them, so they always agree. A scope that is not offered is dropped from a request, a default that is not offered is never granted, and a request that asks for nothing that is offered is refused rather than silently producing a token that can do nothing. Narrowing the offer later never breaks a token already issued, because a token keeps the scopes it was minted with.

The service

ApiTokenService, registered under that name in the service locator.

api_token_service = service_proxy("ApiTokenService")

row, plaintext = api_token_service.mint(user, "laptop", ["write_spl"], ttl_days=90)
api_token_service.verify(plaintext)       # row, or None if unknown/revoked/expired
api_token_service.find(plaintext)         # row whatever its state, to explain a refusal
api_token_service.revoke(row.id, user)    # only the owner can revoke
api_token_service.touch(row)              # last_used_at, at most once every 5 minutes
api_token_service.authenticate(email, password)  # (user, None) or (None, reason)
api_token_service.header_aliases()        # extra headers a token is read from

mint returns the plaintext once. Nothing else in the product can ever produce it again.

A scope that writes (scopes.scope_writes, and a name no feature registered counts as one) is only granted to an account that may act sensitively (auth's User.may_act_sensitively): one carried over from an older site confirms its address first. mint raises EmailUnconfirmed, a ValueError naming the scopes, for anyone else. The token endpoint answers it with 403 and {"code": "email_unconfirmed", "scopes": [...], "confirm_url": ...}, and the token form starts such an account from the defaults that only read, marks the scopes that wait, and sends it to confirm its address if it ticks one. Tokens the account already holds keep working whatever they may do: require_token checks a token's scopes, not its owner's address.

The page that shows a new token sends no Referer, is not cached and runs no script of another site (auth's keep_token_private).

Guarding a route

from splent_io.splent_feature_apikeys.decorators import require_token

@some_bp.route("/api/v1/spls", methods=["POST"])
@require_token("write_spl")
def publish():
    g.api_user   # the owner
    g.api_token  # the presenting token

require_token() with no scope accepts any usable token. For routes where a token is one of several ways in, call resolve_token(scope) directly: it returns (api_token, None) or (None, (response, status)). bearer_token() tells whether the request presents a token at all, without checking it.

A token travels in Authorization: Bearer <token>. Clients written against another convention can send it raw in a header the product names in APIKEYS_HEADER_ALIASES, and every guarded route accepts it there too. When both are present the Bearer header wins.

[tool.splent.config]
APIKEYS_HEADER_ALIASES = ["X-API-Key"]

curl https://<product>/api/v1/auth/whoami -H "X-API-Key: splent_..."

Endpoints

curl -X POST https://<product>/api/v1/auth/tokens \
     -H "Content-Type: application/json" \
     -d '{"email": "dev@example.com", "password": "...", "name": "laptop"}'

curl https://<product>/api/v1/auth/whoami \
     -H "Authorization: Bearer splent_..."

Omitting ttl_days gives the product default; sending it as null gives a token that never expires.

Failed credential attempts are throttled, and a refusal is a 429 with a Retry-After header and the code rate_limited. Three budgets are counted. One address against every account and one address against one account are checked before the password is, and one account from every address together only after wrong credentials, so the right password is never refused because a stranger made noise. The counts live in a table of the product's database that auth owns (auth_throttle_failure), so every gunicorn worker and every container shares them. Until auth's migration has created that table each worker counts on its own and says so in the log. An account is counted however its address is spelled. The database matches addresses under its collation, so dëveloper@example.com or a full-width spelling reaches the same account, and both budgets are keyed on the account it resolves to, never on the typed text. The budget of one address against every account stops a caller spraying one password over many accounts. A token does not clear it, and it sits far above what an office or a campus behind one address gets wrong honestly.

Users are created inactive and an administrator activates them, so an account still waiting is answered with 403 and a message that says exactly that, never with "wrong password".

Pages

• /developer/tokens lists the owner's tokens, by prefix, with a revoke button.
• /developer/tokens/new creates one and shows its plaintext once.

The pages extend shell('app'), so they follow SPLENT_SHELL_APP.

Menus

The feature declares two entries in the framework's menu registry, and an application shell that draws menu_sections() shows them to every signed-in account.

A product hides or reorders them by key in [tool.splent.layout.menu]. Another feature puts its developer link in the same section with its own register_menu_item(..., section="developer").

For one minor, a link also appears in the authenticated sidebar (layout.authenticated_sidebar hook), for the shells that draw that slot. A shell draws the registry or the slots, never both. The next minor drops the hook and the slot below.

Developer links

Right after that link the sidebar entry opens the slot apikeys.sidebar.developer, so other features can put their developer links next to the tokens. Each one renders its own sidebar item, and an empty slot renders nothing. A shell that draws the menu registry does not draw this slot.

from flask import render_template
from splent_framework.hooks.template_hooks import register_template_hook

def api_docs_link():
    return render_template("hooks/sidebar_api_docs.html")

register_template_hook("apikeys.sidebar.developer", api_docs_link, order=10)

When an account is deleted

A token acts as its owner, so it goes with the owner. auth sends user-deleting from the database session just before an account is deleted, whoever deletes it (the accounts screen, the admin panel's generic CRUD, the terminal), and this feature deletes that account's tokens through the same session, in the same transaction. See signals.py.

Configuration

All of them have working defaults, so the feature needs no .env entry.

Install

This feature counts failed logins through auth's shared throttle (splent_io.splent_feature_auth.throttle and its migration auth0003_throttle), which auth v1.18.0 and earlier do not have. Pin it with an auth release that ships them, and release that auth first. With an older auth the app stops at startup on an ImportError.

splent feature:install splent-io/splent_feature_apikeys
splent db:migrate splent_feature_apikeys
splent db:upgrade

Tests

splent feature:test splent_feature_apikeys