Overview Realm Settings Endpoints

Introduction

Use the /overview PATCH and POST endpoints to customize client-side login pages, integrate an SMTP server, configure outgoing emails, and upload logos.

Prerequisites

1. Complete the Enablement and Header Steps in the Admin API Guide

2. Have access to the application code that calls to the API endpoint(s)

3. (OPTIONAL) Have an SMTP server with which to integrate to receive SecureAuth emails

/overview Endpoints

Note

The following endpoints are prepended with the URL, https://<SecureAuth IdP Domain>/api/v1/realms/<realm ID>, if running SecureAuth IdP v9.1 – in which realm ID is the ID number of the realm to configure –

or https://<SecureAuth IdP Domain>/api/v2/realms/<realm ID>, if runningSecureAuth IdP v9.2 or later

Overview Settings /overview PATCH Endpoint

Notice

Use this endpoint to configure the realm's overview settings, including general realm description, SMTP server integration, SecureAuth email messaging, and client-side login page information.

HTTP Method	Endpoint	Example	SecureAuth IdP version
PATCH	/overview	https://secureauth.company.com/api/v2/realms/26/overview	v9.2 or later

Tip

Defaulted values in bold

Field	Description	Accepted Values	Note
realmName	Automatically assigned when created and cannot be changed	N / A
realmDescription	Internal note to briefly describe purpose of realm	any
companyLogoFile	Logo image that appears on client-side login pages	file path, .png, .jpeg, .gif	Must upload image to appliance using /overview/companylogo endpoint Uploading image also changes field to new file path
applicationLogoFile	Logo image that appears on the Secure Portal page that is associated to realm	file path, .png, .jpeg, .gif	Must upload image to appliance using /overview/applicationlogo endpoint Uploading image also changes field to new file path
documentTitle	Title that displays on the browser tab of client-side login pages	any
pageHeader	Title that displays at the top of client-side login pages, typically same as documentTitle	any
theme	Theme selected for look and feel of client-side pages	2012 2013 2016 Light Legacy OTP App Default	The 2012 and Legacy themes are deprecated in SecureAuth IdP v9.2 For appliances upgraded to version 9.2, if either the 2012 or Legacy theme was implemented prior to the upgrade, that theme will be converted to the 2016 Light theme
usernameDisplay	Property mapped to the directory attribute of preferred username displayed on (some) post-authentication pages	AuthenticatedUserId FirstName LastName Phone1 Phone2 Phone3 Phone4 Email1 Email2 Email3 Email4 AuxId1 AuxId2 AuxId3 AuxId4 AuxId5 AuxId6 AuxId7 AuxId8 AuxId9 AuxId10 Email1UsernameOnly Email2UsernameOnly Email3UsernameOnly Email4UsernameOnly CustomToken
usernameLocation	Where the preferred username is displayed on post-authentication page	NotShown ShowInHeader
forgotUsernameUrl	URL of forgot username realm for end-users to access during login	full URL or /<Forgot Username realmName>
forgotUsernamePageLocation	Where forgot username URL is displayed on client-side login pages	PageFooter UnderInputField
forgotPasswordUrl	URL of forgot password realm for end-users to access during login	full URL or /<Forgot Password realmName>
forgotPasswordPageLocation	Where forgot password URL is displayed on client-side login pages	PageFooter UnderInputField
restartLoginUrl	URL to restart end-users' login process	defaulted to <current realm>/restart.aspx, otherwise full URL of preferred destination
restartLoginPageLocation	Where restart login URL is displayed on client-side login pages	NotShown Footer Header Dynamic
copyrightInformation	Copyright information displayed in the footer of the client-side pages	any
eulaUrl	URL for company's end-user license agreement	full URL
disclaimerPageLocation	Where disclaimer information is displayed on client-side pages	NotShown PageFooter
smtp	Settings for SMTP server integration	N / A	Required to enable SecureAuth emails, including OTPs and other account notifications
serverAddress	Address of SMTP server through which SecureAuth emails are sent	any	Required field for SMTP configuration
port	SMTP's required port	any, default 25	Required field for SMTP configuration
username	Username of the SMTP account that has rights to send emails	any
password	Password associated to the SMTP account username	any
domain	Domain name of the SMTP server	any	Required only for authentication purposes, otherwise leave empty
useSsl	Enable Secure Socket Layer that acts as encrypted tunnel through which emails are sent	true false
email	Settings for SecureAuth emails	N / A
logoFile	Logo image that appears on SecureAuth emails	file path, .png, .jpeg, .gif	Must upload image to appliance using /overview/emaillogo endpoint Uploading image also changes field to new file path
subject	Subject of the OTP email	any
showPasscodeInSubject	Enable passcode information to display in email subject	true false
senderAddress	Email address that displays in the From field	any
senderName	Alias name for the email address that displays in the From field	any
template	Template used for SecureAuth OTP emails	OTPEmailTemplate OTPEmailTemplate2013 Custom Template Name**	** Non-SecureAuth IdP template that must be added to appliance through Web Admin UI before setting template to custom name via API

Parameters	Success Response
{ "realmName": "SecureAuth26", "realmDescription": "", "companyLogoFile": "~/Images/SecureAuth_Logo_OnBlack.png", "applicationLogoFile": "~/Images/SecureAuth_Logo_OnBlack.png", "documentTitle": "Secure Access", "pageHeader": "Secure Access to App", "theme": "2016 Light", "usernameDisplay": "AuthenticatedUserId", "usernameLocation": "NotShown", "forgotUsernameUrl": "", "forgotUsernamePageLocation": "PageFooter", "forgotPasswordUrl": "", "forgotPasswordPageLocation": "PageFooter", "restartLoginUrl": "", "restartLoginPageLocation": "Footer", "copyrightInformation": "Copyright 2016 SecureAuth Corp. All rights reserved.", "eulaUrl": "", "disclaimerPageLocation": "NotShown", "smtp": { "serverAddress": "", "port": 25, "username": "", "password": "", "domain": "", "useSsl": false }, "email": { "logoFile": "~/Images/SecureAuth_Logo_OnBlack.png", "subject": "SecureAuth One Time Registration Code", "showPasscodeInSubject": "False", "senderAddress": "do-not-reply@company.com", "senderName": "SecureAuth Support", "template": "OTPEmailTemplate" } }	{ "status": "Success", "message": [] }

Parameters

Success Response

{
        "realmName": "SecureAuth26",
        "realmDescription": "",
        "companyLogoFile": "~/Images/SecureAuth_Logo_OnBlack.png",
        "applicationLogoFile": "~/Images/SecureAuth_Logo_OnBlack.png",
        "documentTitle": "Secure Access",
        "pageHeader": "Secure Access to App",
        "theme": "2016 Light",
        "usernameDisplay": "AuthenticatedUserId",
        "usernameLocation": "NotShown",
        "forgotUsernameUrl": "",
        "forgotUsernamePageLocation": "PageFooter",
        "forgotPasswordUrl": "",
        "forgotPasswordPageLocation": "PageFooter",
        "restartLoginUrl": "",
        "restartLoginPageLocation": "Footer",
        "copyrightInformation": "Copyright 2016 SecureAuth Corp. All rights reserved.",
        "eulaUrl": "",
        "disclaimerPageLocation": "NotShown",
        "smtp": {
                "serverAddress": "",
                "port": 25,
                "username": "",
                "password": "",
                "domain": "",
                "useSsl": false
        },
        "email": {
                "logoFile": "~/Images/SecureAuth_Logo_OnBlack.png",
                "subject": "SecureAuth One Time Registration Code",
                "showPasscodeInSubject": "False",
                "senderAddress": "do-not-reply@company.com",
                "senderName": "SecureAuth Support",
                "template": "OTPEmailTemplate"
        }
}

{
  "status": "Success",
  "message": []
}

Upload Company Logo /overview/companylogo POST Endpoint

Notice

Use this endpoint to upload a company logo image to the appliance and apply it to the realm. This image displays on the client-side login pages.

HTTP Method	Endpoint	Example	SecureAuth IdP version
POST	/overview/companylogo	https://secureauth.company.com/api/v2/realms/26/overview/companylogo	v9.2 or later

Upload Application Logo /overview/applicationlogo POST Endpoint

Notice

Use this endpoint to upload an application logo image to the appliance and apply it to the realm. This image displays on the Secure Portal page that is configured to include this realm.

HTTP Method	Endpoint	Example	SecureAuth IdP version
POST	/overview/applicationlogo	https://secureauth.company.com/api/v2/realms/26/overview/applicationlogo	v9.2 or later

Upload Email Logo /overview/emaillogo POST Endpoint

Notice

Use this endpoint to upload an email logo image to the appliance and apply it to the realm. This image displays in emails sent to end-users by SecureAuth, including OTP messages and account update notifications.

HTTP Method	Endpoint	Example	SecureAuth IdP version
POST	/overview/emaillogo	https://secureauth.company.com/api/v2/realms/26/overview/emaillogo	v9.2 or later

In this section:

Overview Realm Settings Endpoints

Introduction

Prerequisites

/overview Endpoints

Note

Overview Settings /overview PATCH Endpoint

Notice

Tip

Upload Company Logo /overview/companylogo POST Endpoint

Notice

Upload Application Logo /overview/applicationlogo POST Endpoint

Notice

Upload Email Logo /overview/emaillogo POST Endpoint

Notice

Search results