Secrets

A User Secret is how passwords, API keys, multi-factor authentication and backup codes are defined and stored within the system. They provide a method for user’s to authenticate themselves using a trusted known secret.

Passwords

Users that wish to authenticate via a password can create exactly one secret of type password. Password secrets are hashed using the Argon2 algorithm in memory before being transmitted to the database to ensure maximal protection of the password data.

In the event that a password secret is lost or stolen the /users/:id/recover endpoint can be used to reset the password secret and provide a new one.

API Keys

Application keys are used to provide programmatic access to the sytem on behalf of a user. The API key is a unique string, typically a hash, that is created for purposes of identifying users for programmatic functions. The API key can be provided by the user upon creation, or randomly generated by the service. Once an API key secret is created the value is returned in the response and can never be returned again.

Similar to password secrets, API key secrets are hashed with the Argon2 algorithm in-memory before being transmitted and stored to the database.

Multi-Factor Authentication

Users desiring an extra level of protection may enable multi-factor authentication. Multi-factor authentication is enabled by creating a secret of type mfa. Once created an additional request must be sent to /users/:userId/secrets/:id/enroll containing a valid TOTP code to confirm that the end user has successfully registered their MFA device. Once successfully confirmed, all future authentication requests using a password secret will require MFA validation.

MFA Backup Codes

Additionally, upon successful enrollment of an MFA secret, a set of backup codes are automatically generated and returned to the user for safe keeping. These codes may be used at any time as a one-time authentication password secret. Backup codes are not subject to further multi-factor authentication validation. If all backup codes have been used then the user must recover their account using the /users/:id/recover endpoint.

Device

A device secret is used to provide frictionless single-sign on authentication by trusted devices. This is typically a deterministic hash made by the trusted device using a universally unique identifier. Device secrets are not subject to multi-factor authentication requirements. Similar to password secrets, device secrets are hashed with the Argon2 algorithm in-memory before being transmitted and stored to the database.