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-expiringMail the owners of tokens about to expire (APIKEYS_EXPIRY_NOTICE_DAYS).
-
$
splent feature:apikeys purgeRemove the tokens revoked or expired more than APIKEYS_PURGE_AFTER_DAYS ago.
-
$
splent feature:apikeys revoke-all EMAILRevoke 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
Used by
Listens to
user-deletinguser-disableduser-password-changed
In product lines
-
marketplace_spl
Optional in this line
Needs
auth -
openhubs_spl
Optional in this line
Needs
auth
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