Templating
How to use templates to theme your authentication domain
NOTE: This is only available to Pro plans and up
Templating
All of the pages present under an authentication domain (for example, the login
page, login success page, password entry page, etc.) are customizable. They are
based on Jinja templates,
allowing a high degree of customizability while remaining fast and easy to use.
How templates are implemented
All pages take the form of a static HTML file, which links to a global CSS file.
This allows for simple customizations to the colors present on a given page,
while also supporting fully custom designs.
Restrictions
All templates uploaded to Authproject must be under 300KB in size. This is
done to keep the templates lightweight and easily handled by our servers.
Samples
For example, the login pages looks like the following:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Login</title>
<!-- Bootstrap CSS v5.x CDN -->
<link
href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css"
rel="stylesheet"
/>
<link href="/static/style.css" rel="stylesheet" />
</head>
<body>
<div class="container">
<div class="row justify-content-center">
<div class="card login-card">
<div class="login-card-title">Login to Your Account</div>
<div class="login-card-body">
<form method="POST" action="/login">
{% if message %}
<div class="mb-3">
<p class="text-primary text-center">{{ message }}</p>
</div>
{% endif %} {% if error %}
<div class="mb-3">
<p class="text-danger text-center">{{ error }}</p>
</div>
{% endif %}
<div class="mb-3">
<label for="inputEmail" class="form-label">Email address</label>
<input
type="email"
class="form-control"
id="inputEmail"
name="email"
placeholder="Enter email"
/>
</div>
<button type="submit" class="btn btn-success w-100 btn-square">
Login
</button>
<a href="/reset" class="text-success">
<p class="text-center pt-3">Reset password</p>
</a>
<a href="/signup" class="text-success">
<p class="text-center">Sign Up</p>
</a>
</form>
</div>
</div>
</div>
<div class="row">
<footer class="text-center mt-4">
<small
>Powered by <a href="https://authproject.com">Authproject</a></small
>
</footer>
</div>
</div>
</body>
</html>
Explanation
The HTML is structured into three primary parts:
- The header, which includes relevant CSS
- The body, which utilizes Jinja templates
- The footer, which is simply “Powered by Authproject”
While not required, it is recommended that all templates include the global
style.css
file for theming. It must contain valid CSS, and is not given any
variables to be used in the template. That is to say, the file should be CSS
without any Jinja syntax.
The Body
The body is composed of HTML templated with Jinja. Each page is passed a set of
variables (described on the individual page’s documentation), and can perform
actions based on those variables’ contents. For example, the Login page is
passed the following:
message
- A message to be displayed to the user, but not an errorerror
- An error to be displayed to the user
These simple variables contain pre-formatted text strings to transparently
display to the user in the page.
The footer is simple in this page - it simply has a link to Authproject.
Ready to get started?
To see more on templates, browse the page documentation in the side bar.
To sign up for Authproject, simply visit
ours home page and contact us.
1 - Template Tutorial
Tutorial to write your own templates in Authproject
Read this page and follow the guide to build your own templates in Authproject.
Tutorial
The first step is to select the template to edit. In our case, we are going to
be customizing the Login page to have custom colors.
TODO: Complete this with screenshots once the dashboard is complete.
2 - Page Reference
Reference documentation for each template page
2.1 - Dashboard
The main user account dashboard, displaying available authentication options and user session details.
Dashboard
Title: Dashboard
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: The main user account dashboard, displaying available authentication options and user session details.
1. Property Dashboard > email
Title: User Email
Description: The email address of the user.
2. Property Dashboard > first_factor_option_names
Title: First Factor Option Names
| |
---|
Type | object or null |
Required | No |
Description: Human-readable names for first factor options.
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- | No | string | No | - | - |
2.1. Property Dashboard > first_factor_option_names > additionalProperties
3. Property Dashboard > first_factor_options
Title: First Factor Options
| |
---|
Type | array of string or null |
Required | No |
Description: Available first factor authentication methods.
| Array restrictions |
---|
Min items | N/A |
Max items | N/A |
Items unicity | False |
Additional items | False |
Tuple validation | See below |
3.1. Dashboard > first_factor_options > first_factor_options items
4. Property Dashboard > second_factor_option_names
Title: Second Factor Option Names
| |
---|
Type | object or null |
Required | No |
Description: Human-readable names for second factor options.
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- | No | string | No | - | - |
4.1. Property Dashboard > second_factor_option_names > additionalProperties
5. Property Dashboard > second_factor_options
Title: Second Factor Options
| |
---|
Type | array of string or null |
Required | No |
Description: Available second factor authentication methods.
| Array restrictions |
---|
Min items | N/A |
Max items | N/A |
Items unicity | False |
Additional items | False |
Tuple validation | See below |
5.1. Dashboard > second_factor_options > second_factor_options items
6. Property Dashboard > sessions
Title: User Sessions
| |
---|
Type | array or null |
Required | No |
Description: Active user sessions with details.
| Array restrictions |
---|
Min items | N/A |
Max items | N/A |
Items unicity | False |
Additional items | False |
Tuple validation | See below |
6.1. Dashboard > sessions > SchemasSessionSchema
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Defined in | #/definitions/SchemasSessionSchema |
6.1.1. Property Dashboard > sessions > sessions items > expires_at
Title: Expires At
Description: Expiration time of the session.
6.1.2. Property Dashboard > sessions > sessions items > ip_address
Title: IP Address
Description: Last known IP address of the session.
6.1.3. Property Dashboard > sessions > sessions items > last_user_agent
Title: Last User Agent
Description: User agent of the last request in the session.
6.1.4. Property Dashboard > sessions > sessions items > session_id
Title: Session ID
Description: Unique identifier for the session.
2.2 - Enroll OTP
Enroll a user in One-Time Password (OTP) authentication.
Enroll OTP
Title: Enroll OTP
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: Enroll a user in One-Time Password (OTP) authentication.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful",
"otp_secret": "JBSWY3DPEHPK3PXP",
"otp_url": "otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
- otp_secret | No | string | No | - | OTP Secret |
- otp_url | No | string | No | - | OTP URL |
1. Property Enroll OTP > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Enroll OTP > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
3. Property Enroll OTP > otp_secret
Title: OTP Secret
Description: Secret for the OTP authenticator app
4. Property Enroll OTP > otp_url
Title: OTP URL
Description: URL to configure the OTP authenticator app
2.3 - Enroll WebAuthn
The schema for enrolling a user in WebAuthn (Web Authentication) for two-factor authentication.
Enroll WebAuthn
Title: Enroll WebAuthn
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: The schema for enrolling a user in WebAuthn (Web Authentication) for two-factor authentication.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful",
"options": "<opaque string to be sent to the browser>"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
- options | No | string | No | - | WebAuthn Options |
1. Property Enroll WebAuthn > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Enroll WebAuthn > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
3. Property Enroll WebAuthn > options
Title: WebAuthn Options
Description: WebAuthn options for the user to enroll a new device
2.4 - Login
The first step of the login process, where a user enters their email.
Login
Title: Login
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: The first step of the login process, where a user enters their email.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
1. Property Login > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Login > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
2.5 - Login: Enter OTP
The second step of the login process when using OTP (One-Time Password) authentication.
Login: Enter OTP
Title: Login: Enter OTP
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: The second step of the login process when using OTP (One-Time Password) authentication.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
1. Property Login: Enter OTP > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Login: Enter OTP > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
2.6 - Login: Enter Password
The second step of the login process when using a password for authentication.
Login: Enter Password
Title: Login: Enter Password
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: The second step of the login process when using a password for authentication.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
1. Property Login: Enter Password > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Login: Enter Password > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
2.7 - Login: Magic Link
The second step of the login process when using a magic link for authentication.
Login: Magic Link
Title: Login: Magic Link
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: The second step of the login process when using a magic link for authentication.
2.8 - Login: Magic Link Sent
The second step of the login process where a magic link has been sent to the user.
Login: Magic Link Sent
Title: Login: Magic Link Sent
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: The second step of the login process where a magic link has been sent to the user.
2.9 - Login: Options
The options available to the user during the second step of the login process.
Login: Options
Title: Login: Options
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: The options available to the user during the second step of the login process.
Example:
{
"option_name": {
"magiclink": "Magic Link",
"password": "Password"
},
"options": [
"password",
"magiclink"
]
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- oauth_provider_options | No | array | No | - | OAuth Provider Options |
- options | No | array or null | No | - | Options |
1. Property Login: Options > oauth_provider_options
Title: OAuth Provider Options
Description: List of available OAuth provider options for the user to choose from
Example:
{
"provider_id": "google",
"provider_image_url": "https://example.com/google.png",
"provider_name": "Google"
}
| Array restrictions |
---|
Min items | N/A |
Max items | N/A |
Items unicity | False |
Additional items | False |
Tuple validation | See below |
1.1. Login: Options > oauth_provider_options > SchemasLoginFirstFactorProviderOption
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Defined in | #/definitions/SchemasLoginFirstFactorProviderOption |
1.1.1. Property Login: Options > oauth_provider_options > oauth_provider_options items > provider_id
Title: Provider ID
Description: Unique identifier for the OAuth provider
Example:
1.1.2. Property Login: Options > oauth_provider_options > oauth_provider_options items > provider_image_url
Title: Provider Image URL
Description: URL to the image representing the OAuth provider
Example:
"https://example.com/google.png"
1.1.3. Property Login: Options > oauth_provider_options > oauth_provider_options items > provider_name
Title: Provider Name
Description: Human-readable name for the OAuth provider
Example:
2. Property Login: Options > options
Title: Options
| |
---|
Type | array or null |
Required | No |
Description: List of available options for the user to choose from
Example:
{
"option_id": "password",
"option_name": "Password"
}
| Array restrictions |
---|
Min items | N/A |
Max items | N/A |
Items unicity | False |
Additional items | False |
Tuple validation | See below |
2.1. Login: Options > options > SchemasLoginFirstFactorOption
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Defined in | #/definitions/SchemasLoginFirstFactorOption |
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- option_id | No | string | No | - | Option ID |
- option_name | No | string | No | - | Option Name |
2.1.1. Property Login: Options > options > options items > option_id
Title: Option ID
Description: Unique identifier for the login option
Example:
2.1.2. Property Login: Options > options > options items > option_name
Title: Option Name
Description: Human-readable name for the login option
Example:
2.10 - Login: Success
A successful login.
Login: Success
Title: Login: Success
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: A successful login.
2.11 - Login: TFA Options
Display available TFA (Two-Factor Authentication) options for a user during login.
Login: TFA Options
Title: Login: TFA Options
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: Display available TFA (Two-Factor Authentication) options for a user during login.
Example:
{
"option_name": {
"otp": "One-Time Password",
"webauthn": "WebAuthn"
},
"options": [
"otp",
"webauthn"
]
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- option_name | No | object or null | No | - | TFA Option Names |
- options | No | array of string or null | No | - | TFA Options |
1. Property Login: TFA Options > option_name
Title: TFA Option Names
| |
---|
Type | object or null |
Required | No |
Description: Map of TFA option IDs to human-readable names
Example:
{
"otp": "One-Time Password",
"webauthn": "WebAuthn"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- | No | string | No | - | - |
1.1. Property Login: TFA Options > option_name > additionalProperties
2. Property Login: TFA Options > options
Title: TFA Options
| |
---|
Type | array of string or null |
Required | No |
Description: List of available TFA option IDs for the user
Examples:
| Array restrictions |
---|
Min items | N/A |
Max items | N/A |
Items unicity | False |
Additional items | False |
Tuple validation | See below |
2.1. Login: TFA Options > options > options items
2.12 - Login: WebAuthn
The second step of the login process when using WebAuthn for authentication.
Login: WebAuthn
Title: Login: WebAuthn
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: The second step of the login process when using WebAuthn for authentication.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
1. Property Login: WebAuthn > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Login: WebAuthn > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
2.13 - Reset Password
The first step of the password reset process where a user requests a password reset link.
Reset Password
Title: Reset Password
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: The first step of the password reset process where a user requests a password reset link.
2.14 - Reset Password: Email Sent
A response indicating that a password reset link has been sent to the user’s email.
Reset Password: Email Sent
Title: Reset Password: Email Sent
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: A response indicating that a password reset link has been sent to the user’s email.
2.15 - Reset Password: Set Password
Schema for setting a new password during the password reset process.
Reset Password: Set Password
Title: Reset Password: Set Password
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: Schema for setting a new password during the password reset process.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful",
"reset_token": "abc123xyz"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
- reset_token | No | string | No | - | Reset Token |
1. Property Reset Password: Set Password > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Reset Password: Set Password > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
3. Property Reset Password: Set Password > reset_token
Title: Reset Token
Description: The token used to verify the password reset request
Example:
2.16 - Signup
Step 1 in the signup process where a new user registers with their email.
Signup
Title: Signup
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: Step 1 in the signup process where a new user registers with their email.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
1. Property Signup > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Signup > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
2.17 - Signup: Create Password
Create a password during the signup process.
Signup: Create Password
Title: Signup: Create Password
| |
---|
Type | object |
Required | No |
Additional properties | Not allowed |
Description: Create a password during the signup process.
Example:
{
"error": "Invalid credentials",
"message": "Logout successful"
}
Property | Pattern | Type | Deprecated | Definition | Title/Description |
---|
- error | No | string | No | - | Error |
- message | No | string | No | - | Message |
1. Property Signup: Create Password > error
Title: Error
Description: Human-readable message to be displayed about an error that occurred
Example:
2. Property Signup: Create Password > message
Title: Message
Description: Human-readable message to display to the user. It being present is not indicative of an error
Example:
2.18 - Signup: Success
A successful signup response.
Signup: Success
Title: Signup: Success
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: A successful signup response.
2.19 - style.css
The global style.css file.
style.css
Title: style.css
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: The global style.css file.
2.20 - Verification Error
An error response during the verification process.
Verification Error
Title: Verification Error
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: An error response during the verification process.
2.21 - Verification Success
A successful verification response.
Verification Success
Title: Verification Success
| |
---|
Type | object |
Required | No |
Additional properties | Any type allowed |
Description: A successful verification response.