branding

Creates, updates, deletes, gets or lists a branding resource.

Overview

Name	branding
Type	Resource
Id	entra_id.organization.branding

Fields

The following fields are returned by SELECT queries:

get

Retrieved navigation property

Name	Datatype	Description
id	string	The unique identifier for an entity. Read-only.
backgroundColor	string	Color that appears in place of the background image in low-bandwidth connections. We recommend that you use the primary color of your banner logo or your organization color. Specify this in hexadecimal format, for example, white is #FFFFFF.
backgroundImage	string (base64url)	Image that appears as the background of the sign-in page. The allowed types are PNG or JPEG not smaller than 300 KB and not larger than 1920 × 1080 pixels. A smaller image reduces bandwidth requirements and make the page load faster.
backgroundImageRelativeUrl	string	A relative URL for the backgroundImage property that is combined with a CDN base URL from the cdnList to provide the version served by a CDN. Read-only.
bannerLogo	string (base64url)	A banner version of your company logo that appears on the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.
bannerLogoRelativeUrl	string	A relative URL for the bannerLogo property that is combined with a CDN base URL from the cdnList to provide the read-only version served by a CDN. Read-only.
cdnList	array	A list of base URLs for all available CDN providers that are serving the assets of the current resource. Several CDN providers are used at the same time for high availability of read requests. Read-only.
contentCustomization		Represents the content options to be customized throughout the authentication flow for a tenant. NOTE: Supported by Microsoft Entra External ID in external tenants only.
customAccountResetCredentialsUrl	string	A custom URL for resetting account credentials. This URL must be in ASCII format or non-ASCII characters must be URL encoded, and not exceed 128 characters.
customCSS	string (base64url)	CSS styling that appears on the sign-in page. The allowed format is .css format only and not larger than 25 KB.
customCSSRelativeUrl	string	A relative URL for the customCSS property that is combined with a CDN base URL from the cdnList to provide the version served by a CDN. Read-only.
customCannotAccessYourAccountText	string	A string to replace the default 'Can't access your account?' self-service password reset (SSPR) hyperlink text on the sign-in page. This text must be in Unicode format and not exceed 256 characters.
customCannotAccessYourAccountUrl	string	A custom URL to replace the default URL of the self-service password reset (SSPR) 'Can't access your account?' hyperlink on the sign-in page. This URL must be in ASCII format or non-ASCII characters must be URL encoded, and not exceed 128 characters. DO NOT USE. Use customAccountResetCredentialsUrl instead.
customForgotMyPasswordText	string	A string to replace the default 'Forgot my password' hyperlink text on the sign-in form. This text must be in Unicode format and not exceed 256 characters.
customPrivacyAndCookiesText	string	A string to replace the default 'Privacy and Cookies' hyperlink text in the footer. This text must be in Unicode format and not exceed 256 characters.
customPrivacyAndCookiesUrl	string	A custom URL to replace the default URL of the 'Privacy and Cookies' hyperlink in the footer. This URL must be in ASCII format or non-ASCII characters must be URL encoded, and not exceed 128 characters.
customResetItNowText	string	A string to replace the default 'reset it now' hyperlink text on the sign-in form. This text must be in Unicode format and not exceed 256 characters. DO NOT USE: Customization of the 'reset it now' hyperlink text is currently not supported.
customTermsOfUseText	string	A string to replace the the default 'Terms of Use' hyperlink text in the footer. This text must be in Unicode format and not exceed 256 characters.
customTermsOfUseUrl	string	A custom URL to replace the default URL of the 'Terms of Use' hyperlink in the footer. This URL must be in ASCII format or non-ASCII characters must be URL encoded, and not exceed 128characters.
favicon	string (base64url)	A custom icon (favicon) to replace a default Microsoft product favicon on a Microsoft Entra tenant.
faviconRelativeUrl	string	A relative url for the favicon above that is combined with a CDN base URL from the cdnList to provide the version served by a CDN. Read-only.
headerBackgroundColor	string	The RGB color to apply to customize the color of the header.
headerLogo	string (base64url)	A company logo that appears in the header of the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.
headerLogoRelativeUrl	string	A relative URL for the headerLogo property that is combined with a CDN base URL from the cdnList to provide the read-only version served by a CDN. Read-only.
localizations	array	Add different branding based on a locale.
loginPageLayoutConfiguration		Represents the layout configuration to be displayed on the login page for a tenant.
loginPageTextVisibilitySettings		Represents the various texts that can be hidden on the login page for a tenant.
signInPageText	string	Text that appears at the bottom of the sign-in box. Use this to communicate additional information, such as the phone number to your help desk or a legal statement. This text must be in Unicode format and not exceed 1024 characters.
squareLogo	string (base64url)	A square version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.
squareLogoDark	string (base64url)	A square dark version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.
squareLogoDarkRelativeUrl	string	A relative URL for the squareLogoDark property that is combined with a CDN base URL from the cdnList to provide the version served by a CDN. Read-only.
squareLogoRelativeUrl	string	A relative URL for the squareLogo property that is combined with a CDN base URL from the cdnList to provide the version served by a CDN. Read-only.
usernameHintText	string	A string that shows as the hint in the username textbox on the sign-in screen. This text must be a Unicode, without links or code, and can't exceed 64 characters.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	organization_id		Retrieve the default organizational branding object, if the Accept-Language header is set to 0 or default. If no default organizational branding object exists, this method returns a 404 Not Found error. If the Accept-Language header is set to an existing locale identified by the value of its id, this method retrieves the branding for the specified locale. This method retrieves only non-Stream properties, for example, usernameHintText and signInPageText. To retrieve Stream types of the default branding, for example, bannerLogo and backgroundImage, use the GET organizationalBrandingLocalization method.
update	update	organization_id		Update the properties of the default branding object specified by the organizationalBranding resource.
delete	delete	organization_id	If-Match	Delete the default organizational branding object. To delete the organizationalBranding object, all images (Stream types) must first be removed from the object.
background_image	exec	organization_id		Image that appears as the background of the sign-in page. The allowed types are PNG or JPEG not smaller than 300 KB and not larger than 1920 × 1080 pixels. A smaller image reduces bandwidth requirements and make the page load faster.
background_image_2	exec	organization_id	If-Match	Image that appears as the background of the sign-in page. The allowed types are PNG or JPEG not smaller than 300 KB and not larger than 1920 × 1080 pixels. A smaller image reduces bandwidth requirements and make the page load faster.
banner_logo	exec	organization_id		A banner version of your company logo that appears on the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.
banner_logo_2	exec	organization_id	If-Match	A banner version of your company logo that appears on the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.
custom_css	exec	organization_id		CSS styling that appears on the sign-in page. The allowed format is .css format only and not larger than 25 KB.
custom_css_2	exec	organization_id	If-Match	CSS styling that appears on the sign-in page. The allowed format is .css format only and not larger than 25 KB.
favicon	exec	organization_id		A custom icon (favicon) to replace a default Microsoft product favicon on a Microsoft Entra tenant.
favicon_2	exec	organization_id	If-Match	A custom icon (favicon) to replace a default Microsoft product favicon on a Microsoft Entra tenant.
header_logo	exec	organization_id		A company logo that appears in the header of the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.
header_logo_2	exec	organization_id	If-Match	A company logo that appears in the header of the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.
square_logo	exec	organization_id		A square version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.
square_logo_2	exec	organization_id	If-Match	A square version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.
square_logo_dark	exec	organization_id		A square dark version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.
square_logo_dark_2	exec	organization_id	If-Match	A square dark version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
organization_id	string	The unique identifier of organization
If-Match	string	ETag

SELECT examples

get

Retrieve the default organizational branding object, if the Accept-Language header is set to 0 or default. If no default organizational branding object exists, this method returns a 404 Not Found error. If the Accept-Language header is set to an existing locale identified by the value of its id, this method retrieves the branding for the specified locale. This method retrieves only non-Stream properties, for example, usernameHintText and signInPageText. To retrieve Stream types of the default branding, for example, bannerLogo and backgroundImage, use the GET organizationalBrandingLocalization method.

SELECT
id,
backgroundColor,
backgroundImage,
backgroundImageRelativeUrl,
bannerLogo,
bannerLogoRelativeUrl,
cdnList,
contentCustomization,
customAccountResetCredentialsUrl,
customCSS,
customCSSRelativeUrl,
customCannotAccessYourAccountText,
customCannotAccessYourAccountUrl,
customForgotMyPasswordText,
customPrivacyAndCookiesText,
customPrivacyAndCookiesUrl,
customResetItNowText,
customTermsOfUseText,
customTermsOfUseUrl,
favicon,
faviconRelativeUrl,
headerBackgroundColor,
headerLogo,
headerLogoRelativeUrl,
localizations,
loginPageLayoutConfiguration,
loginPageTextVisibilitySettings,
signInPageText,
squareLogo,
squareLogoDark,
squareLogoDarkRelativeUrl,
squareLogoRelativeUrl,
usernameHintText
FROM entra_id.organization.branding
WHERE organization_id = '{{ organization_id }}' -- required
;

UPDATE examples

update

Update the properties of the default branding object specified by the organizationalBranding resource.

UPDATE entra_id.organization.branding
SET 
id = '{{ id }}',
backgroundColor = '{{ backgroundColor }}',
backgroundImage = '{{ backgroundImage }}',
backgroundImageRelativeUrl = '{{ backgroundImageRelativeUrl }}',
bannerLogo = '{{ bannerLogo }}',
bannerLogoRelativeUrl = '{{ bannerLogoRelativeUrl }}',
cdnList = '{{ cdnList }}',
contentCustomization = '{{ contentCustomization }}',
customAccountResetCredentialsUrl = '{{ customAccountResetCredentialsUrl }}',
customCannotAccessYourAccountText = '{{ customCannotAccessYourAccountText }}',
customCannotAccessYourAccountUrl = '{{ customCannotAccessYourAccountUrl }}',
customCSS = '{{ customCSS }}',
customCSSRelativeUrl = '{{ customCSSRelativeUrl }}',
customForgotMyPasswordText = '{{ customForgotMyPasswordText }}',
customPrivacyAndCookiesText = '{{ customPrivacyAndCookiesText }}',
customPrivacyAndCookiesUrl = '{{ customPrivacyAndCookiesUrl }}',
customResetItNowText = '{{ customResetItNowText }}',
customTermsOfUseText = '{{ customTermsOfUseText }}',
customTermsOfUseUrl = '{{ customTermsOfUseUrl }}',
favicon = '{{ favicon }}',
faviconRelativeUrl = '{{ faviconRelativeUrl }}',
headerBackgroundColor = '{{ headerBackgroundColor }}',
headerLogo = '{{ headerLogo }}',
headerLogoRelativeUrl = '{{ headerLogoRelativeUrl }}',
loginPageLayoutConfiguration = '{{ loginPageLayoutConfiguration }}',
loginPageTextVisibilitySettings = '{{ loginPageTextVisibilitySettings }}',
signInPageText = '{{ signInPageText }}',
squareLogo = '{{ squareLogo }}',
squareLogoDark = '{{ squareLogoDark }}',
squareLogoDarkRelativeUrl = '{{ squareLogoDarkRelativeUrl }}',
squareLogoRelativeUrl = '{{ squareLogoRelativeUrl }}',
usernameHintText = '{{ usernameHintText }}',
localizations = '{{ localizations }}'
WHERE 
organization_id = '{{ organization_id }}' --required
RETURNING
id,
backgroundColor,
backgroundImage,
backgroundImageRelativeUrl,
bannerLogo,
bannerLogoRelativeUrl,
cdnList,
contentCustomization,
customAccountResetCredentialsUrl,
customCSS,
customCSSRelativeUrl,
customCannotAccessYourAccountText,
customCannotAccessYourAccountUrl,
customForgotMyPasswordText,
customPrivacyAndCookiesText,
customPrivacyAndCookiesUrl,
customResetItNowText,
customTermsOfUseText,
customTermsOfUseUrl,
favicon,
faviconRelativeUrl,
headerBackgroundColor,
headerLogo,
headerLogoRelativeUrl,
localizations,
loginPageLayoutConfiguration,
loginPageTextVisibilitySettings,
signInPageText,
squareLogo,
squareLogoDark,
squareLogoDarkRelativeUrl,
squareLogoRelativeUrl,
usernameHintText;

DELETE examples

delete

Delete the default organizational branding object. To delete the organizationalBranding object, all images (Stream types) must first be removed from the object.

DELETE FROM entra_id.organization.branding
WHERE organization_id = '{{ organization_id }}' --required
AND If-Match = '{{ If-Match }}'
;

Lifecycle Methods

background_image

Image that appears as the background of the sign-in page. The allowed types are PNG or JPEG not smaller than 300 KB and not larger than 1920 × 1080 pixels. A smaller image reduces bandwidth requirements and make the page load faster.

EXEC entra_id.organization.branding.background_image 
@organization_id='{{ organization_id }}' --required
;

background_image_2

Image that appears as the background of the sign-in page. The allowed types are PNG or JPEG not smaller than 300 KB and not larger than 1920 × 1080 pixels. A smaller image reduces bandwidth requirements and make the page load faster.

EXEC entra_id.organization.branding.background_image_2 
@organization_id='{{ organization_id }}' --required, 
@If-Match='{{ If-Match }}'
;

banner_logo

A banner version of your company logo that appears on the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.

EXEC entra_id.organization.branding.banner_logo 
@organization_id='{{ organization_id }}' --required
;

banner_logo_2

A banner version of your company logo that appears on the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.

EXEC entra_id.organization.branding.banner_logo_2 
@organization_id='{{ organization_id }}' --required, 
@If-Match='{{ If-Match }}'
;

custom_css

CSS styling that appears on the sign-in page. The allowed format is .css format only and not larger than 25 KB.

EXEC entra_id.organization.branding.custom_css 
@organization_id='{{ organization_id }}' --required
;

custom_css_2

CSS styling that appears on the sign-in page. The allowed format is .css format only and not larger than 25 KB.

EXEC entra_id.organization.branding.custom_css_2 
@organization_id='{{ organization_id }}' --required, 
@If-Match='{{ If-Match }}'
;

favicon

A custom icon (favicon) to replace a default Microsoft product favicon on a Microsoft Entra tenant.

EXEC entra_id.organization.branding.favicon 
@organization_id='{{ organization_id }}' --required
;

favicon_2

A custom icon (favicon) to replace a default Microsoft product favicon on a Microsoft Entra tenant.

EXEC entra_id.organization.branding.favicon_2 
@organization_id='{{ organization_id }}' --required, 
@If-Match='{{ If-Match }}'
;

header_logo

A company logo that appears in the header of the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.

EXEC entra_id.organization.branding.header_logo 
@organization_id='{{ organization_id }}' --required
;

header_logo_2

A company logo that appears in the header of the sign-in page. The allowed types are PNG or JPEG not larger than 36 × 245 pixels. We recommend using a transparent image with no padding around the logo.

EXEC entra_id.organization.branding.header_logo_2 
@organization_id='{{ organization_id }}' --required, 
@If-Match='{{ If-Match }}'
;

square_logo

A square version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.

EXEC entra_id.organization.branding.square_logo 
@organization_id='{{ organization_id }}' --required
;

square_logo_2

A square version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.

EXEC entra_id.organization.branding.square_logo_2 
@organization_id='{{ organization_id }}' --required, 
@If-Match='{{ If-Match }}'
;

square_logo_dark

A square dark version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.

EXEC entra_id.organization.branding.square_logo_dark 
@organization_id='{{ organization_id }}' --required
;

square_logo_dark_2

A square dark version of your company logo that appears in Windows 10 out-of-box experiences (OOBE) and when Windows Autopilot is enabled for deployment. Allowed types are PNG or JPEG not larger than 240 x 240 pixels and not more than 10 KB in size. We recommend using a transparent image with no padding around the logo.

EXEC entra_id.organization.branding.square_logo_dark_2 
@organization_id='{{ organization_id }}' --required, 
@If-Match='{{ If-Match }}'
;