Themes APIs - Home - FusionAuth

1. Overview

This API has been available since 1.8.0

UI login themes can be configured to enable custom branding for your FusionAuth login workflow. Themes are configured per Tenant. The following APIs are provided to manage Themes.

Create a Theme
Retrieve a Theme
Update a Theme
Delete a Theme

2. Create a Theme

3. Retrieve a Theme

Retrieve all of the Themes

URI

GET /api/theme

Retrieve a Theme by Id

URI

GET /api/theme/{themeId}

Table 1. Request Parameters
themeId [UUID] Required	The unique Id of the Theme to retrieve.

3.1. Response

The response for this API contains either a single Theme or all of the Themes. When you call this API with an Id the response will contain a single Theme. When you call this API without an Id the response will contain all of the themes. Both response types are defined below along with an example JSON response.

Table 2. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 3. Response Body
theme.id [UUID]	The Id of the Theme.
theme.insertInstant [Integer]	The instant that the theme was added to the FusionAuth database.
theme.lastUpdateInstant [Integer]	The instant that the theme was last updated in the FusionAuth database.
theme.loginTemplate.emailComplete [String]	A FreeMarker template that is rendered when the user requests the /email/complete page. This page is used after a user has verified their email address by clicking the URL in the email. After FusionAuth has updated their user object to indicate that their email was verified, the browser is redirected to this page.
theme.loginTemplate.emailSend [String]	A FreeMarker template that is rendered when the user requests the /email/send page. This page is used after a user has asked for the verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
theme.loginTemplate.emailVerify [String]	A FreeMarker template that is rendered when the user requests the /email/verify page by clicking the URL from the verification email and the `verificationId` has expired. FusionAuth expires `verificationId` after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.
theme.loginTemplate.helpers [String]	A FreeMarker template that contains all of the macros and templates used by the rest of the `loginTheme` FreeMarker templates (i.e. `oauth2Authorize`). This allows you to configure the general layout of your UI configuration and login theme without having to copy and paste HTML into each of the templates.
theme.loginTemplate.oauth2Authorize [String]	A FreeMarker template that is rendered when the user requests the /oauth2/authorize page. This is the main login page for FusionAuth and is used for all interactive OAuth and OpenId Connect workflows.
theme.loginTemplate.oauth2ChildRegistrationNotAllowed [String]	A FreeMarker template that is rendered when the user requests the /oauth2/child-registration-not-allowed page. This is where the child must provide their parent’s email address to ask their parent to create an account for them.
theme.loginTemplate.oauth2ChildRegistrationNotAllowedComplete [String]	A FreeMarker template that is rendered when the user requests the /oauth2/child-registration-not-allowed-complete page. This is where the browser is taken after the child provides their parent’s email address.
theme.loginTemplate.oauth2CompleteRegistration [String]	A FreeMarker template that is rendered when the user requests the /oauth2/complete-registration page. This page is used for users that have accounts but might be missing required fields.
theme.loginTemplate.oauth2Error [String]	A FreeMarker template that is rendered when the user requests the /oauth2/error page. This page is used if the user starts or is in the middle of the OAuth workflow and any type of error occurs. This could be caused by the user messing with the URL or internally some type of information wasn’t passed between the OAuth endpoints correctly. For example, if you are federating login to an external IdP and that IdP does not properly echo the `state` parameter, FusionAuth’s OAuth workflow will break and this page will be displayed.
theme.loginTemplate.oauth2Register [String]	A FreeMarker template that is rendered when the user requests the /oauth2/register page. This page is used for users that need to register (sign-up)
theme.loginTemplate.oauth2TwoFactor [String]	A FreeMarker template that is rendered when the user requests the /oauth2/two-factor page. This page is used if the user has two-factor authentication enabled and they need to type in their code again. FusionAuth will properly handle the SMS or authenticator app processing on the back end. This page contains the form that the user will put their code into.
theme.loginTemplate.passwordChange [String]	A FreeMarker template that is rendered when the user requests the /password/change page. This page is used if the user is required to change their password or if they have requested a password reset. This page contains the form that allows the user to provide a new password.
theme.loginTemplate.passwordComplete [String]	A FreeMarker template that is rendered when the user requests the /password/complete page. This page is used after the user has successfully updated their password (or reset it). This page should instruct the user that their password was updated and that they need to login again.
theme.loginTemplate.passwordForgot [String]	A FreeMarker template that is rendered when the user requests the /password/forgot page. This page is used when a user starts the forgot password workflow. This page renders the form where the user types in their email address.
theme.loginTemplate.passwordSent [String]	A FreeMarker template that is rendered when the user requests the /password/sent page. This page is used when a user has submitted the forgot password form with their email. FusionAuth does not indicate back to the user if their email address was valid in order to prevent malicious activity that could reveal valid email addresses. Therefore, this page should indicate to the user that if their email was valid, they will receive an email shortly with a link to reset their password.
theme.loginTemplate.registrationComplete [String]	A FreeMarker template that is rendered when the user requests the /registration/complete page. This page is used after a user has verified their email address for a specific application (i.e. a user registration) by clicking the URL in the email. After FusionAuth has updated their registration object to indicate that their email was verified, the browser is redirected to this page.
theme.loginTemplate.registrationSend [String]	A FreeMarker template that is rendered when the user requests the /registration/send page. This page is used after a user has asked for the application specific verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
theme.loginTemplate.registrationVerify [String]	A FreeMarker template that is rendered when the user requests the /registration/verify page by clicking the URL from the application specific verification email and the `verificationId` has expired. FusionAuth expires `verificationId` after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.
theme.loginTemplate.stylesheet [String]	A CSS stylesheet used to style the login page and other templates such as forgot password, and verify email.
theme.name [String]	The name of the theme.

Example Response JSON

{
  "theme": {
    "id": "64773453-bb11-457b-a3d6-7475ec2259d0",
    "insertInstant": 1564006815352,
    "lastUpdateInstant": 1564084258150,
    "loginTemplate": {
      "emailComplete": "[#ftl/]",
      "emailSend": "[#ftl/]",
      "emailVerify": "[#ftl/]",
      "helpers": "[#ftl/]",
      "oauth2Authorize": "[#ftl/]",
      "oauth2ChildRegistrationNotAllowed": "[#ftl/]",
      "oauth2ChildRegistrationNotAllowedComplete": "[#ftl/]",
      "oauth2CompleteRegistration": "[#ftl/]",
      "oauth2Error": "[#ftl/]",
      "oauth2Register": "[#ftl/]",
      "oauth2TwoFactor": "[#ftl/]",
      "passwordChange": "[#ftl/]",
      "passwordComplete": "[#ftl/]",
      "passwordForgot": "[#ftl/]",
      "passwordSent": "[#ftl/]",
      "registrationComplete": "[#ftl/]",
      "registrationSend": "[#ftl/]",
      "registrationVerify": "[#ftl/]",
      "stylesheet": "h1 {\r\n  color: orange;\r\n  text-align: center;\r\n}"
    },
    "name": "Orange Theme"
  }
}

Table 4. Response Body
theme`[x]`.id [UUID]	The Id of the Theme.
theme`[x]`.insertInstant [Integer]	The instant that the theme was added to the FusionAuth database.
theme`[x]`.lastUpdateInstant [Integer]	The instant that the theme was last updated in the FusionAuth database.
theme`[x]`.loginTemplate.emailComplete [String]	A FreeMarker template that is rendered when the user requests the /email/complete page. This page is used after a user has verified their email address by clicking the URL in the email. After FusionAuth has updated their user object to indicate that their email was verified, the browser is redirected to this page.
theme`[x]`.loginTemplate.emailSend [String]	A FreeMarker template that is rendered when the user requests the /email/send page. This page is used after a user has asked for the verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
theme`[x]`.loginTemplate.emailVerify [String]	A FreeMarker template that is rendered when the user requests the /email/verify page by clicking the URL from the verification email and the `verificationId` has expired. FusionAuth expires `verificationId` after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.
theme`[x]`.loginTemplate.helpers [String]	A FreeMarker template that contains all of the macros and templates used by the rest of the `loginTheme` FreeMarker templates (i.e. `oauth2Authorize`). This allows you to configure the general layout of your UI configuration and login theme without having to copy and paste HTML into each of the templates.
theme`[x]`.loginTemplate.oauth2Authorize [String]	A FreeMarker template that is rendered when the user requests the /oauth2/authorize page. This is the main login page for FusionAuth and is used for all interactive OAuth and OpenId Connect workflows.
theme`[x]`.loginTemplate.oauth2ChildRegistrationNotAllowed [String]	A FreeMarker template that is rendered when the user requests the /oauth2/child-registration-not-allowed page. This is where the child must provide their parent’s email address to ask their parent to create an account for them.
theme`[x]`.loginTemplate.oauth2ChildRegistrationNotAllowedComplete [String]	A FreeMarker template that is rendered when the user requests the /oauth2/child-registration-not-allowed-complete page. This is where the browser is taken after the child provides their parent’s email address.
theme`[x]`.loginTemplate.oauth2CompleteRegistration [String]	A FreeMarker template that is rendered when the user requests the /oauth2/complete-registration page. This page is used for users that have accounts but might be missing required fields.
theme`[x]`.loginTemplate.oauth2Error [String]	A FreeMarker template that is rendered when the user requests the /oauth2/error page. This page is used if the user starts or is in the middle of the OAuth workflow and any type of error occurs. This could be caused by the user messing with the URL or internally some type of information wasn’t passed between the OAuth endpoints correctly. For example, if you are federating login to an external IdP and that IdP does not properly echo the `state` parameter, FusionAuth’s OAuth workflow will break and this page will be displayed.
theme`[x]`.loginTemplate.oauth2Register [String]	A FreeMarker template that is rendered when the user requests the /oauth2/register page. This page is used for users that need to register (sign-up)
theme`[x]`.loginTemplate.oauth2TwoFactor [String]	A FreeMarker template that is rendered when the user requests the /oauth2/two-factor page. This page is used if the user has two-factor authentication enabled and they need to type in their code again. FusionAuth will properly handle the SMS or authenticator app processing on the back end. This page contains the form that the user will put their code into.
theme`[x]`.loginTemplate.passwordChange [String]	A FreeMarker template that is rendered when the user requests the /password/change page. This page is used if the user is required to change their password or if they have requested a password reset. This page contains the form that allows the user to provide a new password.
theme`[x]`.loginTemplate.passwordComplete [String]	A FreeMarker template that is rendered when the user requests the /password/complete page. This page is used after the user has successfully updated their password (or reset it). This page should instruct the user that their password was updated and that they need to login again.
theme`[x]`.loginTemplate.passwordForgot [String]	A FreeMarker template that is rendered when the user requests the /password/forgot page. This page is used when a user starts the forgot password workflow. This page renders the form where the user types in their email address.
theme`[x]`.loginTemplate.passwordSent [String]	A FreeMarker template that is rendered when the user requests the /password/sent page. This page is used when a user has submitted the forgot password form with their email. FusionAuth does not indicate back to the user if their email address was valid in order to prevent malicious activity that could reveal valid email addresses. Therefore, this page should indicate to the user that if their email was valid, they will receive an email shortly with a link to reset their password.
theme`[x]`.loginTemplate.registrationComplete [String]	A FreeMarker template that is rendered when the user requests the /registration/complete page. This page is used after a user has verified their email address for a specific application (i.e. a user registration) by clicking the URL in the email. After FusionAuth has updated their registration object to indicate that their email was verified, the browser is redirected to this page.
theme`[x]`.loginTemplate.registrationSend [String]	A FreeMarker template that is rendered when the user requests the /registration/send page. This page is used after a user has asked for the application specific verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
theme`[x]`.loginTemplate.registrationVerify [String]	A FreeMarker template that is rendered when the user requests the /registration/verify page by clicking the URL from the application specific verification email and the `verificationId` has expired. FusionAuth expires `verificationId` after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.
theme`[x]`.loginTemplate.stylesheet [String]	A CSS stylesheet used to style the login page and other templates such as forgot password, and verify email.
theme`[x]`.name [String]	The name of the theme.

Example Response JSON

{
  "themes": [
    {
      "id": "64773453-bb11-457b-a3d6-7475ec2259d0",
      "insertInstant": 1564006815352,
      "lastUpdateInstant": 1564084258150,
      "loginTemplate": {
        "emailComplete": "[#ftl/]",
        "emailSend": "[#ftl/]",
        "emailVerify": "[#ftl/]",
        "helpers": "[#ftl/]",
        "oauth2Authorize": "[#ftl/]",
        "oauth2ChildRegistrationNotAllowed": "[#ftl/]",
        "oauth2ChildRegistrationNotAllowedComplete": "[#ftl/]",
        "oauth2CompleteRegistration": "[#ftl/]",
        "oauth2Error": "[#ftl/]",
        "oauth2Register": "[#ftl/]",
        "oauth2TwoFactor": "[#ftl/]",
        "passwordChange": "[#ftl/]",
        "passwordComplete": "[#ftl/]",
        "passwordForgot": "[#ftl/]",
        "passwordSent": "[#ftl/]",
        "registrationComplete": "[#ftl/]",
        "registrationSend": "[#ftl/]",
        "registrationVerify": "[#ftl/]",
        "stylesheet": "h1 {\r\n  color: orange;\r\n  text-align: center;\r\n}"
      },
      "name": "Orange Theme"
    },
    {
      "id": "75a068fd-e94b-451a-9aeb-3ddb9a3b5987",
      "insertInstant": 1563999505859,
      "lastUpdateInstant": 1564005677559,
      "name": "Default Theme"
    }
  ]
}

4. Update a Theme

This API is used to update an existing Theme.

URI

PUT /api/theme/{themeId}

Table 5. Request Parameters
themeId [UUID] Required	The unique Id of the Theme to update.

Table 6. Request Body
key.name [String] Required	The name of the Key.

Example Request JSON

{
  "key": {
    "name": "OpenID Connect compliant HMAC using SHA-256"
  }
}

4.1. Response

The response for this API contains the Key that was updated.

Table 7. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you are trying to updated doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 8. Response Body
key.algorithm [String]	The algorithm used to encrypt the key.
key.certificate [String]	The RSA or EC X.509 certificate. This field is omitted for HMAC key types.
key.certificateInformation [Map<String, Object]	The RSA or EC certificate information. This field is omitted for HMAC key types.
key.certificateInformation.issuer [String]	The issuer of the RSA or EC certificate. This field is omitted for HMAC key types.
key.certificateInformation.md5Fingerprint [String]	The md5 fingerprint of the RSA or EC certificate. This field is omitted for HMAC key types.
key.certificateInformation.serialNumber [String]	The serial number of the RSA or EC certificate. This field is omitted for HMAC key types.
key.certificateInformation.sha1Fingerprint [String]	The SHA-1 fingerprint of the RSA or EC certificate. This field is omitted for HMAC key types.
key.certificateInformation.sha1Thumbprint [String]	The SHA-1 thumbprint of the RSA or EC certificate. This field is omitted for HMAC key types.
key.certificateInformation.sha256Fingerprint [String]	The SHA-256 fingerprint of the RSA or EC certificate. This field is omitted for HMAC key types.
key.certificateInformation.sha256Thumbprint [String]	The SHA-256 thumbprint of the RSA or EC certificate. This field is omitted for HMAC key types.
key.certificateInformation.subject [String]	The subject of the RSA or EC certificate. This field is omitted for HMAC key types.
key.certificateInformation.validFrom [Integer]	The UNIX time in milliseconds marking the start of the RSA or EC certificate validity period. This field is omitted for HMAC key types.
key.certificateInformation.validTo [Integer]	The UNIX time in milliseconds marking the expiration RSA or EC certificate. This field is omitted for HMAC key types.
key.expirationInstant [Integer]	The instant marking the expiration RSA or EC certificate. This field is omitted for HMAC key types.
key.id [UUID]	The Id of the Key.
key.insertInstant [Integer]	The instant that the key was added to the FusionAuth database.
key.issuer [String]	The issuer of the RSA or EC certificate. This field is omitted for HMAC key types.
key.kid [String]	The key identifier 'kid'.
key.length [String]	The length of the RSA or EC certificate. This field is omitted for HMAC key types.
key.name [String]	The name of the key.
key.publicKey [String]	The RSA or EC certificate public key. This field is omitted for HMAC key types.
key.type [String]	The key type. The possible values are: `EC` `RSA` `HMAC`

Example HMAC Key Response JSON

{
  "key": {
    "algorithm": "HS256",
    "id": "092dbedc-30af-4149-9c61-b578f2c72f59",
    "insertInstant": 1562171137000,
    "kid": "10d51735a5",
    "name": "OpenID Connect compliant HMAC using SHA-256",
    "type": "HMAC"
  }
}

Example RSA Key Response JSON

{
  "key": {
    "algorithm": "RS256",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIICrjCCAZagAwIBAQIQeA4dW+47Q7KuyNuZuZrcTjANBgkqhkiG9w0BAQsFADAT\nMREwDwYDVQQDEwhhY21lLmNvbTAeFw0xOTA3MDMyMTI0MzJaFw0yOTA3MDMyMTI0\nMzJaMBMxETAPBgNVBAMTCGFjbWUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\nMIIBCgKCAQEAnbNGwtU33S4vbipGeIwe/DhLEfc5FaEOHK4WeQ3QF8zZGyI09bNQ\ndkp8uNTFfVehIgmvYHmJWPeaNrYK//qjWAsSvYYoytj1j4BywI8uLSjt8QvzaoFU\nMOi1cBbXM2586R7yTRm7jMk91MLM101zkrf1cmFdRUwTpeJjw66XG3JlTGZCmZsJ\nG7m6+nbe5LHt4CiufmJHujGeFzgwby3jXZtuK1y3ua3380Fv95JyG3TucnMwEw5E\nYQ8Q+dZzNC8OSaKrgmnN0gWdsJ7P7vu6lMy6sXKhvcxo1p+tXywYPFJahxA+rZDG\n16RLbUppCx10q8tIcFKeAyl4eywzBaBLxwIDAQABMA0GCSqGSIb3DQEBCwUAA4IB\nAQBbsHWIBDwW1hFEin0D5BK/rwpCIZ4jlJ9PON4q0rF/tl9+pSzTqMeEqU0NMlJ7\nXm2O5U0i8Sy8Lhemo9qYCZ76qEiHFZwQBmNAC4de92KMcw4Q7q5CVjTGv3X+Avlg\n/c+I+zJLO/IJlzhOvHj+iCeBZDznt6/KlFfXA9EvlznxqZCQHSf2f94UlvBmqbVY\nOfXE5+OQ3URyNyh88g9yClSb4hzu1lmzevZ/AVbe2kTjZQQWB0TmqPg/6SS+nhsa\nuAMK1kSlSK9t6CPz/L7olJeAi7G/PZPaYG1gIFVFaBnYM0rwagQGtPMi1uCERCKr\nkUlBh6gSyN7SGJBvWEh6+zZF\n-----END CERTIFICATE-----",
    "certificateInformation": {
      "issuer": "CN=acme.com",
      "md5Fingerprint": "FC:36:CD:0B:9C:B7:62:F0:A9:16:AE:72:8E:F8:7D:D8",
      "serialNumber": "78:0E:1D:5B:EE:3B:43:B2:AE:C8:DB:99:B9:9A:DC:4E",
      "sha1Fingerprint": "CD:A9:80:5F:4D:37:EB:CD:B4:45:42:DF:76:35:15:E9:89:21:61:B6",
      "sha1Thumbprint": "zamAX0036820RULfdjUV6YkhYbY",
      "sha256Fingerprint": "33:7C:CB:4C:23:3B:F5:22:49:2F:68:C5:FA:D1:6E:3C:72:54:CB:3C:E6:D1:70:08:55:FC:43:24:9A:98:05:CF",
      "sha256Thumbprint": "M3zLTCM79SJJL2jF-tFuPHJUyzzm0XAIVfxDJJqYBc8",
      "subject": "CN=acme.com",
      "validFrom": 1562189072183,
      "validTo": 1877808272183
    },
    "expirationInstant": 1877808272183,
    "id": "780e1d5b-ee3b-43b2-aec8-db99b99adc4e",
    "insertInstant": 1562189072183,
    "issuer": "acme.com",
    "kid": "zamAX0036820RULfdjUV6YkhYbY",
    "length": 2048,
    "name": "SHA-256 with RSA",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnbNGwtU33S4vbipGeIwe\n/DhLEfc5FaEOHK4WeQ3QF8zZGyI09bNQdkp8uNTFfVehIgmvYHmJWPeaNrYK//qj\nWAsSvYYoytj1j4BywI8uLSjt8QvzaoFUMOi1cBbXM2586R7yTRm7jMk91MLM101z\nkrf1cmFdRUwTpeJjw66XG3JlTGZCmZsJG7m6+nbe5LHt4CiufmJHujGeFzgwby3j\nXZtuK1y3ua3380Fv95JyG3TucnMwEw5EYQ8Q+dZzNC8OSaKrgmnN0gWdsJ7P7vu6\nlMy6sXKhvcxo1p+tXywYPFJahxA+rZDG16RLbUppCx10q8tIcFKeAyl4eywzBaBL\nxwIDAQAB\n-----END PUBLIC KEY-----",
    "type": "RSA"
  }
}

5. Delete a Theme

This API is used to delete a Theme.

URI

DELETE /api/theme/{themeId}

Table 9. Request Parameters
themeId [UUID] Required	The unique Id of the Theme to delete.

5.1. Response

This API does not return a JSON response body.

Table 10. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you are trying to delete doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.