fix: add warn log insufficient scope for branding templates export (#1047)

kushalshit27 · web-flow · commit f306cc951dbf · 2025-03-13T17:30:28.000+05:30
* fix: handle warn insufficient scope error for branding templates export

* docs: add branding management section with YAML and directory examples
diff --git a/docs/resource-specific-documentation.md b/docs/resource-specific-documentation.md
@@ -368,3 +368,69 @@ Contents of `reset_email_by_code.json`
   "html": "./reset_email_by_code.html"
 }
 ```
+
+## Branding
+
+This resource allows to manage branding within your Auth0 tenant. Auth0 can be customized with a look and feel that aligns with your organization's brand requirements and user expectations. `universal_login` template can be customized (make sure to add `read:custom_domains` scope to export templates).
+
+**YAML Example**
+
+Folder structure when in YAML mode.
+
+```yaml
+branding:
+  colors:
+    page_background: '#FF4F40'
+    primary: '#2A2E35'
+  favicon_url: https://example.com/favicon.png
+  font:
+    url: https://example.com/font.woff
+  logo_url: https://example.com/logo.png
+  templates:
+    - template: universal_login
+      body: ./branding_templates/universal_login.html
+```
+
+**Directory Example**
+
+Folder structure when in directory mode.
+
+```json
+{
+  "colors": {
+    "page_background": "#FF4F40",
+    "primary": "#2A2E35"
+  },
+  "favicon_url": "https://example.com/favicon.png",
+  "font": {
+    "url": "https://example.com/font.woff"
+  },
+  "logo_url": "https://example.com/logo.png"
+}
+```
+
+For `universal_login` template `templates/` will be created.
+
+- `templates/universal_login.html`
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    {%- auth0:head -%}
+  </head>
+  <body>
+    {%- auth0:widget -%}
+    <div>page teamplate</div>
+  </body>
+</html>
+```
+
+- `templates/universal_login.json`
+
+```json
+{
+  "template": "universal_login",
+  "body": "./universal_login.html"
+}
+```
diff --git a/src/tools/auth0/handlers/branding.ts b/src/tools/auth0/handlers/branding.ts
@@ -73,7 +73,14 @@ export default class BrandingHandler extends DefaultHandler {
       return branding;
     } catch (err) {
       log.debug(`Error calling branding API, ${err.message}, status code: ${err.statusCode}`);
-      if (err.statusCode === 403) return branding;
+
+      if (err.statusCode === 403) {
+        log.warn(
+          'Insufficient scope the read:custom_domains scope is not set. Branding templates will not be exported.'
+        );
+        return branding;
+      }
+
       if (err.statusCode === 404) return branding;
       if (err.statusCode === 501) return branding;
       throw err;
diff --git a/test/tools/auth0/handlers/branding.tests.js b/test/tools/auth0/handlers/branding.tests.js
@@ -93,6 +93,34 @@ describe('#branding handler', () => {
       });
     });
 
+    it('should handle insufficient scope error and not export branding templates', async () => {
+      const auth0 = {
+        branding: {
+          getSettings: () => ({
+            data: {
+              logo_url: 'https://example.com/logo.png',
+            },
+          }),
+          getUniversalLoginTemplate: () => ({
+            body: html,
+          }),
+        },
+        customDomains: {
+          getAll: () => {
+            const err = new Error('Insufficient scope');
+            err.statusCode = 403;
+            return Promise.reject(err);
+          },
+        },
+      };
+
+      const handler = new branding.default({ client: auth0 });
+      const data = await handler.getType();
+      expect(data).to.deep.equal({
+        logo_url: 'https://example.com/logo.png',
+      });
+    });
+
     it('should update branding settings without templates if no templates set', (done) => {
       const auth0 = {
         branding: {
