Branding

{
  "data": {
    "logo_url": "https://cdn.example.com/acme/logo.png",
    "logomark_url": "https://cdn.example.com/acme/logomark.svg",
    "primary_color": "#5B2AC3",
    "accent_color": "#F59E0B",
    "dashboard_name": "Acme Support",
    "support_email": "support@acme.example.com",
    "custom_domain": "support.acme.example.com",
    "favicon_url": "https://cdn.example.com/acme/favicon.ico",
    "terms_url": "https://acme.example.com/terms",
    "privacy_url": "https://acme.example.com/privacy",
    "colors": { "primary": "#5B2AC3", "accent": "#F59E0B" },
    "typography": { "heading_font": "Inter", "body_font": "Inter" },
    "organization_id": "org_01HZQX4E7JQ4M2E2H2DM9XE5",
    "inherited_from_organization_id": null,
    "inherits_from_parent": false,
    "inherited_fields": null
  },
  "meta": {
    "request_id": "req_branden",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

{
  "data": {
    "logo_url": "https://cdn.example.com/acme/logo.png",
    "logomark_url": "https://cdn.example.com/acme/logomark.svg",
    "primary_color": "#5B2AC3",
    "accent_color": "#F59E0B",
    "dashboard_name": "Acme Support",
    "support_email": "support@acme.example.com",
    "custom_domain": "support.acme.example.com",
    "favicon_url": "https://cdn.example.com/acme/favicon.ico",
    "terms_url": "https://acme.example.com/terms",
    "privacy_url": "https://acme.example.com/privacy",
    "colors": { "primary": "#5B2AC3", "accent": "#F59E0B" },
    "typography": { "heading_font": "Inter", "body_font": "Inter" },
    "organization_id": "org_01HZQX4E7JQ4M2E2H2DM9XE5",
    "inherited_from_organization_id": null,
    "inherits_from_parent": false,
    "inherited_fields": null
  },
  "meta": {
    "request_id": "req_branden",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Resolve the effective branding for your tenant

One read returns the branding your dashboard, hosted sign-in page, and white-label surfaces should render with. The resolver walks a three-step chain — your own settings first, your reseller parent second, the platform default theme last — and answers it in one envelope so no surface needs a second round-trip. Two auth paths reach the same resolver. With a tenant API key you pass X-API-Key and resolve your own tenant; an unsigned render — the white-labelled sign-in page before anyone logs in — passes X-Tenant-Host instead, with no key. Both calls below hit GET /api/v1/branding/effective and return the same envelope shape.

cURL

curl https://api.orbit.devotel.io/api/v1/branding/effective \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/branding/effective",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

{
  "data": {
    "logo_url": "https://cdn.example.com/acme/logo.png",
    "logomark_url": "https://cdn.example.com/acme/logomark.svg",
    "primary_color": "#5B2AC3",
    "accent_color": "#F59E0B",
    "dashboard_name": "Acme Support",
    "support_email": "support@acme.example.com",
    "custom_domain": "support.acme.example.com",
    "favicon_url": "https://cdn.example.com/acme/favicon.ico",
    "terms_url": "https://acme.example.com/terms",
    "privacy_url": "https://acme.example.com/privacy",
    "colors": { "primary": "#5B2AC3", "accent": "#F59E0B" },
    "typography": { "heading_font": "Inter", "body_font": "Inter" },
    "organization_id": "org_01HZQX4E7JQ4M2E2H2DM9XE5",
    "inherited_from_organization_id": null,
    "inherits_from_parent": false,
    "inherited_fields": null
  },
  "meta": {
    "request_id": "req_branden",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Every field is returned; a field you never set (and a parent, if any, never set) comes back null, which signals “fall back to the platform default theme.”

Resolution chain

Tenant override wins. Fields you set directly — under Settings → Branding in the dashboard, or via the organization branding API — are self-authoritative.
Reseller parent fills the gaps. For a subaccount with inherits_from_parent: true, any unset field is pulled from the parent organization. inherited_from_organization_id names the org that supplied values, and inherited_fields maps each inherited field to that org, so the dashboard can badge “Inherited from Acme HQ.”
Null means platform default. A field still null after both steps renders with the unbranded default theme — the merger never invents a value.

The help-center theming fields (help_logo_url, help_primary_color, help_secondary_color, help_header_links, help_show_powered_by) are returned on the same record; they control the public help center and join the chain exactly like the dashboard fields. When branding cannot be resolved — a transient database blip, or a subdomain that is still provisioning — the read still returns 200 with every field nulled, so the shell your authenticating user is waiting on never fails to render.

The response carries Cache-Control: private, max-age=60. Cache it for a minute per client rather than polling on every render.

Custom domains before a session exists

The same resolution powers your white-labelled sign-in page. The page passes its domain in X-Tenant-Host — no API key — and receives the resolved branding of the tenant that registered that domain, so custom.acme.example.com shows your logo and palette before anyone signs in.

cURL

curl https://api.orbit.devotel.io/api/v1/branding/effective \
  -H "X-Tenant-Host: custom.acme.example.com"

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/branding/effective",
  {
    headers: { "X-Tenant-Host": "custom.acme.example.com" },
  },
);
console.log(await res.json());

This path sends no X-API-Key — the header that identifies the tenant is X-Tenant-Host, and the response’s custom_domain names the registered domain it resolved to. The unsigned path is IP-rate-limited at a lower ceiling than authenticated calls; the resolution chain above is unchanged.

Unsigned resolution — response example

When X-Tenant-Host resolves to an active tenant domain, the resolver returns the full effective branding envelope. For a subaccount mirroring a parent reseller, inherited_from_organization_id points to the providing parent organization and inherits_from_parent is true:

{
  "data": {
    "logo_url": "https://cdn.example.com/acme/logo.png",
    "logomark_url": "https://cdn.example.com/acme/logomark.svg",
    "primary_color": "#5B2AC3",
    "accent_color": "#F59E0B",
    "dashboard_name": "Acme Support",
    "support_email": "support@acme.example.com",
    "custom_domain": "custom.acme.example.com",
    "favicon_url": "https://cdn.example.com/acme/favicon.ico",
    "terms_url": "https://acme.example.com/terms",
    "privacy_url": "https://acme.example.com/privacy",
    "help_logo_url": "https://cdn.example.com/acme/help-logo.png",
    "help_primary_color": "#5B2AC3",
    "help_secondary_color": "#F59E0B",
    "help_header_links": [
      {
        "label": "Documentation",
        "url": "https://docs.acme.example.com"
      }
    ],
    "help_show_powered_by": false,
    "organization_id": "org_01HZQX4E7JQ4M2E2H2DM9XE5",
    "inherited_from_organization_id": "org_01HYPARENTORG897M4N5P6Q",
    "inherits_from_parent": true,
    "inherited_fields": {
      "logo_url": "org_01HYPARENTORG897M4N5P6Q",
      "primary_color": "org_01HYPARENTORG897M4N5P6Q",
      "accent_color": "org_01HYPARENTORG897M4N5P6Q"
    }
  },
  "meta": {
    "request_id": "req_brand_unsigned_reseller",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Unknown or unprovisioned host — 200 with nulls

When the domain passed in X-Tenant-Host is not registered to an active tenant, or when branding cannot be resolved during a database blip, the endpoint returns HTTP 200 with every field nulled rather than failing. The authenticating user’s browser shell falls back cleanly to the platform default theme:

{
  "data": {
    "logo_url": null,
    "logomark_url": null,
    "primary_color": null,
    "accent_color": null,
    "dashboard_name": null,
    "support_email": null,
    "custom_domain": null,
    "favicon_url": null,
    "terms_url": null,
    "privacy_url": null,
    "help_logo_url": null,
    "help_primary_color": null,
    "help_secondary_color": null,
    "help_header_links": null,
    "help_show_powered_by": null,
    "organization_id": null,
    "inherited_from_organization_id": null,
    "inherits_from_parent": false,
    "inherited_fields": null
  },
  "meta": {
    "request_id": "req_brand_unknown_host",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Rate-limit on the unsigned path — 429 envelope

Because X-Tenant-Host is unauthenticated and resolves domains before a session exists, it is rate-limited by caller IP (RATE_LIMIT_PUBLIC_UNAUTH: 10 requests per minute). Exceeding this limit returns HTTP 429:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry in 54 seconds.",
    "status": 429,
    "retry_after": 54
  },
  "meta": {
    "request_id": "req_brand_rate_limit",
    "timestamp": "2026-08-26T12:00:00.000Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
  }
}

API Reference

All Endpoints

Resolve the effective branding for your tenant

Resolution chain

Custom domains before a session exists

Unsigned resolution — response example

Unknown or unprovisioned host — 200 with nulls

Rate-limit on the unsigned path — 429 envelope

​Resolve the effective branding for your tenant

​Resolution chain

​Custom domains before a session exists

​Unsigned resolution — response example

​Unknown or unprovisioned host — 200 with nulls

​Rate-limit on the unsigned path — 429 envelope

Resolve the effective branding for your tenant

Resolution chain

Custom domains before a session exists

Unsigned resolution — response example

Unknown or unprovisioned host — 200 with nulls

Rate-limit on the unsigned path — 429 envelope