apikeys

git.splent.io/splent-io/splent_feature_apikeys

v0.12.1 full security

About

Developer API tokens: mint, verify, revoke, a registry where features declare the scopes they check, and a token decorator for the product's own API

Provides

Models
ApiTokenApiTokenResource
Services
ApiTokenService
Routes
/admin/tokens/admin/tokens/<int:user_id>/revoke-all/api/v1/auth/tokens/api/v1/auth/tokens/current/api/v1/auth/whoami/developer/tokens/developer/tokens/<int:token_id>/revoke/developer/tokens/new/developer/tokens/revoke-all
Hooks filled
layout.authenticated_sidebar
Translations
es

Commands

  • $ splent feature:apikeys notify-expiring

    Mail the owners of tokens about to expire (APIKEYS_EXPIRY_NOTICE_DAYS).

  • $ splent feature:apikeys purge

    Remove the tokens revoked or expired more than APIKEYS_PURGE_AFTER_DAYS ago.

  • $ splent feature:apikeys revoke-all EMAIL

    Revoke every token of ANY account, by email.

Run them in your workspace once the feature is installed in the selected product.

Configuration

Setting Default What it does
APIKEYS_DEFAULT_TTL_DAYS 90 How long a key issued without an explicit expiry is good for.
APIKEYS_MAX_TTL_DAYS 365 The longest life a token may be given, on the form and on the API.
APIKEYS_ALLOW_NO_EXPIRY false Every token expires. A product whose clients need tokens that never do allows them here, and then an empty life on the form, or "ttl_days": null on the API, issues one.
APIKEYS_EXPIRY_NOTICE_DAYS 30,7 The owner is mailed this many days before a token expires, once for each threshold, by `splent feature:apikeys notify-expiring`, which the product schedules (README, Lifecycle). Empty mails nothing.
APIKEYS_MAX_ACTIVE_TOKENS 50 Tokens one account may hold that are neither revoked nor expired. A token asked for past it is refused until the owner revokes one. 0 turns it off.
APIKEYS_REQUIRED_IDENTITY empty The sign-in provider an account has to have linked to create a token, such as "orcid". Empty lets any account. The tokens it already holds keep working.
APIKEYS_PURGE_AFTER_DAYS 90 Days a revoked or expired token is kept, so a client that presents it is told why it stopped working, before `splent feature:apikeys purge` removes it.
APIKEYS_REVOKE_ON password_changed,account_disabled What happening to an account revokes its tokens: a new password (a reset link, My account, an administrator, the terminal) and the account being switched off. Deleting an account always deletes its tokens.
APIKEYS_MAX_LOGIN_ATTEMPTS 5 Rate limiting on the exchange endpoint, which takes a password. The first limit counts one address against one account, the second one account from every address, so a single guesser and a pool of addresses are both bounded. Counted in auth's shared table, so every worker and every container of the product shares one count. That table and the throttle module come with an auth newer than v1.18.0, so pin the two together.
APIKEYS_LOGIN_WINDOW_SECONDS 300 No description yet.
APIKEYS_MAX_ACCOUNT_ATTEMPTS 20 No description yet.
APIKEYS_MAX_ADDRESS_ATTEMPTS 200 The third counts one address against every account together, so spraying one password over many accounts is bounded too. Far above what an office or campus behind one address gets wrong honestly.
APIKEYS_THROTTLE_MAX_KEYS 10000 While auth's table is missing (before its migration has run) each worker counts in memory instead. This caps how many counters it holds then, so a flood of distinct addresses cannot grow it without bound.
APIKEYS_MAX_BODY_BYTES 8192 Largest body accepted on the token endpoints. They take a short JSON object, and anything larger is not a client that means well.
APIKEYS_PUBLIC_READS_PER_MINUTE 60 Calls a client without a token may make each minute, from one address, to the routes that answer one: require_token(..., public=True), which an API puts on what anyone may read (dataset_api's published datasets, AP-4). Past it the call is answered 429 rate_limited, with Retry-After. Counted in auth's shared table, as the login budgets are. 0 asks every caller for a token, as every route did before.
APIKEYS_SCOPES empty The scopes this product hands out, out of those its features register with register_api_scope (this feature registers read_spl and write_spl). Empty offers every registered scope; a list offers only the scopes named, and an alias among them (read_dataset, say) names the scopes it stands for.
APIKEYS_DEFAULT_SCOPES empty What a token gets when its creator does not choose, and what the token form ticks. Empty grants every offered scope that was registered as a default (register_api_scope(..., default=False) opts a scope out); a name that is not offered is never granted. A product that offers write scopes should list its read scopes here.
APIKEYS_HEADER_ALIASES empty Extra request headers that carry the raw token, besides Authorization: Bearer, for clients built for another convention, for example ["X-API-Key"]. An Authorization: Bearer header always wins.

These are the defaults. A product changes them in its own pyproject.toml, under [tool.splent.config], or in .env.deploy in production.

Dependencies

Requires
Works better with
Listens to
user-deletinguser-disableduser-password-changed

In product lines

Extension points

Hook slots
apikeys.sidebar.developer
Templates
apikeys/admin.htmlapikeys/created.htmlapikeys/identity_required.htmlapikeys/index.htmlapikeys/macros.htmlapikeys/new.htmlhooks/sidebar_tokens.html
Services
ApiTokenService
Models
ApiTokenApiTokenResource
Routes
A refinement can add routes to its blueprint

Other features fill its hook slots. A refinement can override its templates and services or extend its models without forking it.

Compatibility

Python
>=3.13
SPLENT framework
>=1.30.0
Python packages
pytz>=2024.1