This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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:

  1. The header, which includes relevant CSS
  2. The body, which utilizes Jinja templates
  3. The footer, which is simply “Powered by Authproject”

The Header

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 error
  • error - 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

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: The main user account dashboard, displaying available authentication options and user session details.

PropertyPatternTypeDeprecatedDefinitionTitle/Description
- emailNostringNo-User Email
- first_factor_option_namesNoobject or nullNo-First Factor Option Names
- first_factor_optionsNoarray of string or nullNo-First Factor Options
- second_factor_option_namesNoobject or nullNo-Second Factor Option Names
- second_factor_optionsNoarray of string or nullNo-Second Factor Options
- sessionsNoarray or nullNo-User Sessions

1. Property Dashboard > email

Title: User Email

Typestring
RequiredNo

Description: The email address of the user.

2. Property Dashboard > first_factor_option_names

Title: First Factor Option Names

Typeobject or null
RequiredNo

Description: Human-readable names for first factor options.

PropertyPatternTypeDeprecatedDefinitionTitle/Description
- NostringNo--

2.1. Property Dashboard > first_factor_option_names > additionalProperties

Typestring
RequiredNo

3. Property Dashboard > first_factor_options

Title: First Factor Options

Typearray of string or null
RequiredNo

Description: Available first factor authentication methods.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
first_factor_options items-

3.1. Dashboard > first_factor_options > first_factor_options items

Typestring
RequiredNo

4. Property Dashboard > second_factor_option_names

Title: Second Factor Option Names

Typeobject or null
RequiredNo

Description: Human-readable names for second factor options.

PropertyPatternTypeDeprecatedDefinitionTitle/Description
- NostringNo--

4.1. Property Dashboard > second_factor_option_names > additionalProperties

Typestring
RequiredNo

5. Property Dashboard > second_factor_options

Title: Second Factor Options

Typearray of string or null
RequiredNo

Description: Available second factor authentication methods.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
second_factor_options items-

5.1. Dashboard > second_factor_options > second_factor_options items

Typestring
RequiredNo

6. Property Dashboard > sessions

Title: User Sessions

Typearray or null
RequiredNo

Description: Active user sessions with details.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
SchemasSessionSchema-

6.1. Dashboard > sessions > SchemasSessionSchema

Typeobject
RequiredNo
Additional propertiesAny type allowed
Defined in#/definitions/SchemasSessionSchema
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- expires_atNostringNo-Expires At
- ip_addressNostringNo-IP Address
- last_user_agentNostringNo-Last User Agent
- session_idNostringNo-Session ID

6.1.1. Property Dashboard > sessions > sessions items > expires_at

Title: Expires At

Typestring
RequiredNo

Description: Expiration time of the session.

6.1.2. Property Dashboard > sessions > sessions items > ip_address

Title: IP Address

Typestring
RequiredNo

Description: Last known IP address of the session.

6.1.3. Property Dashboard > sessions > sessions items > last_user_agent

Title: Last User Agent

Typestring
RequiredNo

Description: User agent of the last request in the session.

6.1.4. Property Dashboard > sessions > sessions items > session_id

Title: Session ID

Typestring
RequiredNo

Description: Unique identifier for the session.

2.2 - Enroll OTP

Enroll a user in One-Time Password (OTP) authentication.

Enroll OTP

Title: Enroll OTP

Typeobject
RequiredNo
Additional propertiesNot 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"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message
- otp_secretNostringNo-OTP Secret
- otp_urlNostringNo-OTP URL

1. Property Enroll OTP > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Enroll OTP > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

3. Property Enroll OTP > otp_secret

Title: OTP Secret

Typestring
RequiredNo

Description: Secret for the OTP authenticator app

4. Property Enroll OTP > otp_url

Title: OTP URL

Typestring
RequiredNo

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

Typeobject
RequiredNo
Additional propertiesNot 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>"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message
- optionsNostringNo-WebAuthn Options

1. Property Enroll WebAuthn > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Enroll WebAuthn > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

3. Property Enroll WebAuthn > options

Title: WebAuthn Options

Typestring
RequiredNo

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

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: The first step of the login process, where a user enters their email.

Example:

{
    "error": "Invalid credentials",
    "message": "Logout successful"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message

1. Property Login > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Login > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

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

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: The second step of the login process when using OTP (One-Time Password) authentication.

Example:

{
    "error": "Invalid credentials",
    "message": "Logout successful"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message

1. Property Login: Enter OTP > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Login: Enter OTP > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

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

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: The second step of the login process when using a password for authentication.

Example:

{
    "error": "Invalid credentials",
    "message": "Logout successful"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message

1. Property Login: Enter Password > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Login: Enter Password > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

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

Typeobject
RequiredNo
Additional propertiesAny 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

Typeobject
RequiredNo
Additional propertiesAny 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

Typeobject
RequiredNo
Additional propertiesNot 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"
    ]
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- oauth_provider_optionsNoarrayNo-OAuth Provider Options
- optionsNoarray or nullNo-Options

1. Property Login: Options > oauth_provider_options

Title: OAuth Provider Options

Typearray
RequiredNo

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 itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
SchemasLoginFirstFactorProviderOption-

1.1. Login: Options > oauth_provider_options > SchemasLoginFirstFactorProviderOption

Typeobject
RequiredNo
Additional propertiesAny type allowed
Defined in#/definitions/SchemasLoginFirstFactorProviderOption
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- provider_idNostringNo-Provider ID
- provider_image_urlNostringNo-Provider Image URL
- provider_nameNostringNo-Provider Name

1.1.1. Property Login: Options > oauth_provider_options > oauth_provider_options items > provider_id

Title: Provider ID

Typestring
RequiredNo

Description: Unique identifier for the OAuth provider

Example:

"google"

1.1.2. Property Login: Options > oauth_provider_options > oauth_provider_options items > provider_image_url

Title: Provider Image URL

Typestring
RequiredNo

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

Typestring
RequiredNo

Description: Human-readable name for the OAuth provider

Example:

"Google"

2. Property Login: Options > options

Title: Options

Typearray or null
RequiredNo

Description: List of available options for the user to choose from

Example:

{
    "option_id": "password",
    "option_name": "Password"
}
Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
SchemasLoginFirstFactorOption-

2.1. Login: Options > options > SchemasLoginFirstFactorOption

Typeobject
RequiredNo
Additional propertiesAny type allowed
Defined in#/definitions/SchemasLoginFirstFactorOption
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- option_idNostringNo-Option ID
- option_nameNostringNo-Option Name

2.1.1. Property Login: Options > options > options items > option_id

Title: Option ID

Typestring
RequiredNo

Description: Unique identifier for the login option

Example:

"password"

2.1.2. Property Login: Options > options > options items > option_name

Title: Option Name

Typestring
RequiredNo

Description: Human-readable name for the login option

Example:

"Password"

2.10 - Login: Success

A successful login.

Login: Success

Title: Login: Success

Typeobject
RequiredNo
Additional propertiesAny 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

Typeobject
RequiredNo
Additional propertiesNot 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"
    ]
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- option_nameNoobject or nullNo-TFA Option Names
- optionsNoarray of string or nullNo-TFA Options

1. Property Login: TFA Options > option_name

Title: TFA Option Names

Typeobject or null
RequiredNo

Description: Map of TFA option IDs to human-readable names

Example:

{
    "otp": "One-Time Password",
    "webauthn": "WebAuthn"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- NostringNo--

1.1. Property Login: TFA Options > option_name > additionalProperties

Typestring
RequiredNo

2. Property Login: TFA Options > options

Title: TFA Options

Typearray of string or null
RequiredNo

Description: List of available TFA option IDs for the user

Examples:

"otp"
"webauthn"
Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
options items-

2.1. Login: TFA Options > options > options items

Typestring
RequiredNo

2.12 - Login: WebAuthn

The second step of the login process when using WebAuthn for authentication.

Login: WebAuthn

Title: Login: WebAuthn

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: The second step of the login process when using WebAuthn for authentication.

Example:

{
    "error": "Invalid credentials",
    "message": "Logout successful"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message

1. Property Login: WebAuthn > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Login: WebAuthn > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

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

Typeobject
RequiredNo
Additional propertiesAny 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

Typeobject
RequiredNo
Additional propertiesAny 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

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: Schema for setting a new password during the password reset process.

Example:

{
    "error": "Invalid credentials",
    "message": "Logout successful",
    "reset_token": "abc123xyz"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message
- reset_tokenNostringNo-Reset Token

1. Property Reset Password: Set Password > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Reset Password: Set Password > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

3. Property Reset Password: Set Password > reset_token

Title: Reset Token

Typestring
RequiredNo

Description: The token used to verify the password reset request

Example:

"abc123xyz"

2.16 - Signup

Step 1 in the signup process where a new user registers with their email.

Signup

Title: Signup

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: Step 1 in the signup process where a new user registers with their email.

Example:

{
    "error": "Invalid credentials",
    "message": "Logout successful"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message

1. Property Signup > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Signup > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

2.17 - Signup: Create Password

Create a password during the signup process.

Signup: Create Password

Title: Signup: Create Password

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: Create a password during the signup process.

Example:

{
    "error": "Invalid credentials",
    "message": "Logout successful"
}
PropertyPatternTypeDeprecatedDefinitionTitle/Description
- errorNostringNo-Error
- messageNostringNo-Message

1. Property Signup: Create Password > error

Title: Error

Typestring
RequiredNo

Description: Human-readable message to be displayed about an error that occurred

Example:

"Invalid credentials"

2. Property Signup: Create Password > message

Title: Message

Typestring
RequiredNo

Description: Human-readable message to display to the user. It being present is not indicative of an error

Example:

"Logout successful"

2.18 - Signup: Success

A successful signup response.

Signup: Success

Title: Signup: Success

Typeobject
RequiredNo
Additional propertiesAny type allowed

Description: A successful signup response.

2.19 - style.css

The global style.css file.

style.css

Title: style.css

Typeobject
RequiredNo
Additional propertiesAny type allowed

Description: The global style.css file.

2.20 - Verification Error

An error response during the verification process.

Verification Error

Title: Verification Error

Typeobject
RequiredNo
Additional propertiesAny type allowed

Description: An error response during the verification process.

2.21 - Verification Success

A successful verification response.

Verification Success

Title: Verification Success

Typeobject
RequiredNo
Additional propertiesAny type allowed

Description: A successful verification response.