PATCH /v1/branding
- Scope
branding:write- Auth
- Secret key (
sk_…) - Since
- 1.0
Headers
Section titled “Headers”
Minor version; defaults to the environment’s pin.OhAuthCat-Versionstring
Honoured for 24 h; a replay returns the original response.Idempotency-Keystringmin length 1 · max length 255
Request body
Section titled “Request body”
The app name shown in portal invite emails, 1–100 characters without control characters.app_namestring or nullmax length 100
Theme colours as hex (lightBrandingTheme#rgbor#rrggbb). The portal themesprimaryonly (DESIGN.md §6); it always uses its own neutral surfaces and text. The hosted consent screen uses all four (accent, or elseprimary, as its accent); unset colours are the product defaults. A theme whoseforegroundor accent has a contrast below 4.5:1 (WCAG AA) on itsbackground(or the default background) answersparameter_invalidnaming the failing colour, for examplelight.foreground.
Theme colours as hex (darkBrandingTheme#rgbor#rrggbb). The portal themesprimaryonly (DESIGN.md §6); it always uses its own neutral surfaces and text. The hosted consent screen uses all four (accent, or elseprimary, as its accent); unset colours are the product defaults. A theme whoseforegroundor accent has a contrast below 4.5:1 (WCAG AA) on itsbackground(or the default background) answersparameter_invalidnaming the failing colour, for examplelight.foreground.
A URL returned bylogo_urlstring (uri) or nullPOST /v1/branding/logofor this environment (logos are served only from the assets host); any other URL answersparameter_invalid.nullor""removes the logo.
A font family name of at most 100 characters withoutfontstring or null;{}<>"'\\()/*@:or control characters. The hosted consent screen recognisessystem,serifandmonoand uses the system font for any other value.
Corner radius in pixels. Values above 12 are accepted for compatibility but the portal renders at most 12 (DESIGN.md §6) and the hosted consent screen at most 16; new values should be 0–12.radiusinteger or nullmin 0 · max 32
privacy_urlstring (uri) or nullterms_urlstring (uri) or null
A URL returned byfavicon_urlstring (uri) or nullPOST /for this environment;v1/ branding/ favicon nullor""removes it.
A URL returned byfont_urlstring (uri) or nullPOST /v1/branding/fontfor this environment;nullor""removes it.
Separate branding for the setup portal, the consent screen and emails, each falling back to the main branding field by field. On an update the object replaces the stored sets;surfacesBrandingSurfaces{}removes them.
Responses
Section titled “Responses”- 200 OK Branding
- 400 Invalid request. Codes: parameter_invalid, parameter_missing, version_unsupported and resource-specific codes from the catalogue. Error
- 401 Codes: authentication_required, api_key_invalid. Error
- 403 Codes: api_key_scope_missing, ip_not_allowed, plan_limit_reached. Error
- 409 Codes: idempotency_key_reused and resource-specific conflicts. Error
- 429 Code: rate_limited. Retry-After is set. Error
- 503 Code: service_unavailable. Retry-After is set; writes are paused. Error
- default Any other error, including internal_error. Every code is in the error catalogue. Error
Errors share one shape; see the error code catalogue.
curl -X PATCH \ "https://api.ohauthcat.com/v1/branding" \ -H "Authorization: Bearer $OHAUTHCAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "app_name": "example_app_name", "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "logo_url": "https://app.acme.com/callback", "font": "Inter", "radius": 0, "privacy_url": "https://app.acme.com/callback", "terms_url": "https://app.acme.com/callback", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "surfaces": { "portal": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } }, "consent": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } }, "email": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } } }}'const response = await fetch("https://api.ohauthcat.com/v1/branding", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "app_name": "example_app_name", "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "logo_url": "https://app.acme.com/callback", "font": "Inter", "radius": 0, "privacy_url": "https://app.acme.com/callback", "terms_url": "https://app.acme.com/callback", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "surfaces": { "portal": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } }, "consent": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } }, "email": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } } } }),});const data = await response.json();import osimport requests
response = requests.patch( "https://api.ohauthcat.com/v1/branding", headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"}, json={ "app_name": "example_app_name", "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820", }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820", }, "logo_url": "https://app.acme.com/callback", "font": "Inter", "radius": 0, "privacy_url": "https://app.acme.com/callback", "terms_url": "https://app.acme.com/callback", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "surfaces": { "portal": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820", }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820", }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820", }, "card_background": { "light": "#C94820", "dark": "#C94820", }, "text": { "light": "#C94820", "dark": "#C94820", }, "muted_text": { "light": "#C94820", "dark": "#C94820", }, "accent": { "light": "#C94820", "dark": "#C94820", }, "border": { "light": "#C94820", "dark": "#C94820", }, }, }, "consent": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820", }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820", }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820", }, "card_background": { "light": "#C94820", "dark": "#C94820", }, "text": { "light": "#C94820", "dark": "#C94820", }, "muted_text": { "light": "#C94820", "dark": "#C94820", }, "accent": { "light": "#C94820", "dark": "#C94820", }, "border": { "light": "#C94820", "dark": "#C94820", }, }, }, "email": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820", }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820", }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820", }, "card_background": { "light": "#C94820", "dark": "#C94820", }, "text": { "light": "#C94820", "dark": "#C94820", }, "muted_text": { "light": "#C94820", "dark": "#C94820", }, "accent": { "light": "#C94820", "dark": "#C94820", }, "border": { "light": "#C94820", "dark": "#C94820", }, }, }, }, },)data = response.json(){ "object": "branding", "app_name": "example_app_name", "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "logo_url": "https://app.acme.com/callback", "font": "Inter", "radius": 1, "privacy_url": "https://app.acme.com/callback", "terms_url": "https://app.acme.com/callback", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "surfaces": { "portal": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } }, "consent": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } }, "email": { "light": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "dark": { "primary": "#C94820", "background": "#C94820", "foreground": "#C94820", "accent": "#C94820" }, "radius": 0, "logo_url": "https://app.acme.com/callback", "font": "Inter", "favicon_url": "https://app.acme.com/callback", "font_url": "https://app.acme.com/callback", "logo_url_dark": "https://example.com", "colors": { "page_background": { "light": "#C94820", "dark": "#C94820" }, "card_background": { "light": "#C94820", "dark": "#C94820" }, "text": { "light": "#C94820", "dark": "#C94820" }, "muted_text": { "light": "#C94820", "dark": "#C94820" }, "accent": { "light": "#C94820", "dark": "#C94820" }, "border": { "light": "#C94820", "dark": "#C94820" } } } }}