tokeflow.com
DocumentationAPI ReferenceDashboardsSDKsChangelog

Organization profile and branding

Read and update the organization's profile and white-label branding from the Dashboard.

These endpoints back the organization's profile and branding screens. The profile holds the org's compliance identity — legal name, registration, country. Branding holds the white-label surface: logo, colors, and the look customers see in the Customer Portal and hosted flows.

Because Tokeflow is white-label, this branding is what your customers experience as your product. Changes apply to org-wide surfaces on their next load.

These endpoints power the Tokeflow Dashboard UI at the organization level. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-organization-id header, and the signed-in user must be a member of that organization.

The organization object

Returned by the list and retrieve endpoints on this page.

FieldTypeDescription
idstringOrganisation ID.
namestringOrganisation name.
slugstringBusiness Slug.
statusstringOrganisation status.
business_registration_numberstring | nullBusiness registration number (tax ID).
mccstring | nullMerchant Category Code (MCC).
phone_numberstring | nullContact phone number.
address_line1string | nullMerchant address line 1.
address_line2string | nullMerchant address line 2.
citystring | nullCity of the merchant.
statestring | nullState of the merchant.
postal_codestring | nullPostal code of the merchant.
country_codestring | nullCountry code of the merchant.
external_referencestring | nullExternal reference/ID from organization system.
created_atstringDate when the organisation was created. (ISO 8601 UTC).
updated_atstringDate when the organisation was last updated. (ISO 8601 UTC).
brandingobjectBranding information for the organisation.

Endpoints

GET/api/v1/organization

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get organization profile and branding information.

Example request

curl https://api.tokeflow.com/api/v1/organization \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "org_123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "status": "active",
  "business_registration_number": "12345678000199",
  "mcc": "5732",
  "phone_number": "+55 11 99999-0000",
  "address_line1": "123 Main St",
  "address_line2": "Suite 100",
  "city": "S\u00e3o Paulo",
  "state": "SP",
  "postal_code": "12345-678",
  "country_code": "BR",
  "external_reference": "internal_id_99",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-02T00:00:00Z",
  "branding": {
    "theme_primary_color": "#FF5733",
    "theme_secondary_color": "#33C1FF",
    "custom_url": "https://www.acme-corp.com",
    "site_title": "Acme Corp Identity Provider",
    "favicon": "https://www.acme-corp.com/favicon.ico",
    "logo_light_mode": "https://www.acme-corp.com/logo-light.png",
    "logo_dark_mode": "https://www.acme-corp.com/logo-dark.png",
    "collapsible_logo_light_mode": "https://www.acme-corp.com/collapsible-logo-light.png",
    "collapsible_logo_dark_mode": "https://www.acme-corp.com/collapsible-logo-dark.png"
  }
}

PATCH/api/v1/organization

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Update organization profile information.

Request fields

FieldTypeRequiredDescription
namestringYesOrganisation name.
business_registration_numberstring | nullYesBusiness registration number (tax ID).
mccstring | nullYesMerchant Category Code (MCC).
phone_numberstring | nullYesContact phone number.
address_line1string | nullYesMerchant address line 1.
address_line2string | nullYesMerchant address line 2.
citystring | nullYesCity of the merchant.
statestring | nullYesState of the merchant. ISO 3166-2 subdivision code without the country prefix ("SP", not "BR-SP"). Checked against country_code when both are sent.
postal_codestring | nullYesPostal code of the merchant.
country_codestring | nullYesCountry code of the merchant.
external_referencestring | nullYesExternal reference/ID from organization system.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/organization \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "business_registration_number": "12345678000199",
    "mcc": "5732",
    "phone_number": "+55 11 99999-0000",
    "address_line1": "123 Main St",
    "address_line2": "Suite 100",
    "city": "S\u00e3o Paulo",
    "state": "SP",
    "postal_code": "12345-678",
    "country_code": "BR",
    "external_reference": "internal_id_99"
  }'

Example response — 202

{
  "id": "org_123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "status": "active",
  "business_registration_number": "12345678000199",
  "mcc": "5732",
  "phone_number": "+55 11 99999-0000",
  "address_line1": "123 Main St",
  "address_line2": "Suite 100",
  "city": "S\u00e3o Paulo",
  "state": "SP",
  "postal_code": "12345-678",
  "country_code": "BR",
  "external_reference": "internal_id_99",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-02T00:00:00Z",
  "branding": {
    "theme_primary_color": "#FF5733",
    "theme_secondary_color": "#33C1FF",
    "custom_url": "https://www.acme-corp.com",
    "site_title": "Acme Corp Identity Provider",
    "favicon": "https://www.acme-corp.com/favicon.ico",
    "logo_light_mode": "https://www.acme-corp.com/logo-light.png",
    "logo_dark_mode": "https://www.acme-corp.com/logo-dark.png",
    "collapsible_logo_light_mode": "https://www.acme-corp.com/collapsible-logo-light.png",
    "collapsible_logo_dark_mode": "https://www.acme-corp.com/collapsible-logo-dark.png"
  }
}

GET/api/v1/organization/branding

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get organization branding information.

Example request

curl https://api.tokeflow.com/api/v1/organization/branding \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "theme_primary_color": "#FF5733",
  "theme_secondary_color": "#33C1FF",
  "custom_url": "https://www.acme-corp.com",
  "site_title": "Acme Corp Identity Provider",
  "favicon": "https://www.acme-corp.com/favicon.ico",
  "logo_light_mode": "https://www.acme-corp.com/logo-light.png",
  "logo_dark_mode": "https://www.acme-corp.com/logo-dark.png",
  "collapsible_logo_light_mode": "https://www.acme-corp.com/collapsible-logo-light.png",
  "collapsible_logo_dark_mode": "https://www.acme-corp.com/collapsible-logo-dark.png"
}

PATCH/api/v1/organization/branding

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Update organization branding information.

Request fields

FieldTypeRequiredDescription
theme_primary_colorstring | nullNoPrimary color in hex format.
theme_secondary_colorstring | nullNoSecondary color in hex format.
custom_urlstring | nullNoCustom URL for the organization.
site_titlestring | nullNoSite title for the organization.
faviconstring | nullNoFavicon URL for the organization.
logo_light_modestring | nullNoLogo URL for light mode.
logo_dark_modestring | nullNoLogo URL for dark mode.
collapsible_logo_light_modestring | nullNoCollapsible logo URL for light mode.
collapsible_logo_dark_modestring | nullNoCollapsible logo URL for dark mode.
show_name_with_logobooleanNoShow the site title (or merchant name) alongside the logo in the customer portal instead of replacing it.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/organization/branding \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "theme_primary_color": "#FF5733",
    "theme_secondary_color": "#33C1FF",
    "custom_url": "https://www.acme-corp.com",
    "site_title": "Acme Corp Identity Provider",
    "favicon": "https://www.acme-corp.com/favicon.ico",
    "logo_light_mode": "https://www.acme-corp.com/logo-light.png",
    "logo_dark_mode": "https://www.acme-corp.com/logo-dark.png",
    "collapsible_logo_light_mode": "https://www.acme-corp.com/collapsible-logo-light.png",
    "collapsible_logo_dark_mode": "https://www.acme-corp.com/collapsible-logo-dark.png",
    "show_name_with_logo": false
  }'

Example response — 202

{
  "theme_primary_color": "#FF5733",
  "theme_secondary_color": "#33C1FF",
  "custom_url": "https://www.acme-corp.com",
  "site_title": "Acme Corp Identity Provider",
  "favicon": "https://www.acme-corp.com/favicon.ico",
  "logo_light_mode": "https://www.acme-corp.com/logo-light.png",
  "logo_dark_mode": "https://www.acme-corp.com/logo-dark.png",
  "collapsible_logo_light_mode": "https://www.acme-corp.com/collapsible-logo-light.png",
  "collapsible_logo_dark_mode": "https://www.acme-corp.com/collapsible-logo-dark.png"
}

Errors

Errors use the standard envelope. The most common cases here:

HTTPMeaning
400Invalid parameters or a state that does not allow this operation.
401Missing, expired, or invalid Dashboard session token.
403Authenticated, but the signed-in user lacks access to this entity.
404The record does not exist or is not visible to this entity.

On this page

The organization objectEndpointsGET /api/v1/organizationPATCH /api/v1/organizationGET /api/v1/organization/brandingPATCH /api/v1/organization/brandingErrorsRelated