authnzerver.actions.apikey module

This contains functions to drive API key related auth actions.

authnzerver.actions.apikey.issue_apikey(payload: dict, raiseonfail: bool = False, override_authdb_path: str = None, override_permissions_json: str = None, config: types.SimpleNamespace = None) → dict[source]

Issues a new API key.

Parameters:
  • payload (dict) –

    The payload dict must have the following keys:

    • issuer: str, the entity that will be designated as the API key issuer
    • audience: str, the service this API key is being issued for
    • subject: str, the specific API endpoint API key is being issued for
    • apiversion: int or str, the API version that the API key is valid for
    • expires_days: int, the number of days after which the API key will expire
    • not_valid_before: float or int, the amount of seconds after utcnow() when the API key becomes valid
    • user_id: int, the user ID of the user requesting the API key
    • user_role: str, the user role of the user requesting the API key
    • ip_address: str, the IP address to tie the API key to
    • user_agent: str, the browser user agent requesting the API key
    • session_token: str, the session token of the user requesting the API key
  • raiseonfail (bool) – If True, will raise an Exception if something goes wrong.
  • override_authdb_path (str or None) – If given as a str, is the alternative path to the auth DB.
  • override_permissions_json (str or None) – If given as a str, is the alternative path to the permissions JSON to use. This is used to check if the user_id is allowed to actually request an API key.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

The dict returned is of the form:

{'success': True or False,
 'apikey': apikey dict,
 'expires': expiry datetime in ISO format,
 'messages': list of str messages if any}

Return type:

dict

Notes

API keys are tied to an IP address and client header combination.

This function will return a dict with all the API key information. This entire dict should be serialized to JSON, encrypted and time-stamp signed by the frontend as the final “API key”, and finally sent back to the client.

authnzerver.actions.apikey.revoke_apikey(payload: dict, raiseonfail: bool = False, override_authdb_path: str = None, override_permissions_json: str = None, config: types.SimpleNamespace = None) → dict[source]

Revokes an API key.

Parameters:
  • payload (dict) –

    This dict contains the following keys:

    • apikey_dict: the decrypted and verified API key info dict from the frontend.
    • user_id: the user ID of the person revoking this key. Only superusers or staff can revoke an API key that doesn’t belong to them.
    • user_role: the user ID of the person revoking this key. Only superusers or staff can revoke an API key that doesn’t belong to them.
  • raiseonfail (bool) – If True, will raise an Exception if something goes wrong.
  • override_authdb_path (str or None) – If given as a str, is the alternative path to the auth DB.
  • override_permissions_json (str or None) – If given as a str, is the alternative path to the permissions JSON to use. This is used to check if the user_id is allowed to actually revoke (“delete”) an API key.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

The dict returned is of the form:

{'success': True if API key was revoked and False otherwise,
 'messages': list of str messages if any}

Return type:

dict
authnzerver.actions.apikey.verify_apikey(payload: dict, raiseonfail: bool = False, override_authdb_path: str = None, override_permissions_json: str = None, config: types.SimpleNamespace = None) → dict[source]

Checks if an API key is valid.

Parameters:
  • payload (dict) –

    This dict contains a single key:

    • apikey_dict: the decrypted and verified API key info dict from the frontend.
    • user_id: the user ID of the person wanting to verify this key.
    • user_role: the user role of the person wanting to verify this key.
  • raiseonfail (bool) – If True, will raise an Exception if something goes wrong.
  • override_authdb_path (str or None) – If given as a str, is the alternative path to the auth DB.
  • override_permissions_json (str or None) – If given as a str, is the alternative path to the permissions JSON to use. This is used to check if the user_id is allowed to actually verify (“read”) an API key.
  • config (SimpleNamespace object or None) – An object containing systemwide config variables as attributes. This is useful when the wrapping function needs to pass in some settings directly from environment variables.
Returns:

The dict returned is of the form:

{'success': True if API key is OK and False otherwise,
 'messages': list of str messages if any}

Return type:

dict