> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsales.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update whitelabel

> Rebrand: name, the artwork URLs, the palette and the email chrome, effective on the next app load and the next email. domain changes only while pending_domain (422 on a live brand: disable and create anew). A new email_from_address on another domain drops the old proof: verify it again. At least one field, else 422 nothing_to_update.

Contract:
- MCP tool `update_whitelabel`, registry package `mcp.id/whitelabels`, mount `id.partner`.
- Operation `update`, response envelope `update`.
- Flags: none.



## OpenAPI

````yaml /api-reference/id/openapi.yaml patch /api/whitelabels/{sid}
openapi: 3.0.3
info:
  title: 'GetSales public contract: gs.service.id'
  description: >-
    The identity service: the signed-in account, its workspaces and their
    members, the sessions and the gtm-api workspaces a team reaches; the API
    keys, OAuth clients and standing consents; the Paddle billing of the pool a
    buyer holds (catalog, subscriptions, transactions, payment methods); the
    partner's surface (white label brands, their clients, the shares handed to
    workspaces, the certificates behind the brand domains); and the notification
    feed.


    GENERATED. This document is projected from the Zod MCP tool registry in
    `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by
    hand; edit the tool definition and regenerate with `pnpm openapi:public`.


    Surface: the public `/api` contract of `gs.service.id`, 88 operations. This
    is the only OpenAPI document the platform publishes. Internal (`/internal`)
    and health endpoints are deliberately absent: they are not part of any
    contract, they can change without notice, and the service source is their
    only description.


    Conventions:

    - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header.

    - Every success body is an MCP envelope: `success: true` plus one typed
    `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`,
    `group_by`, `action`), and a `meta` block with `trace_id` for support.

    - Every failure is the same `McpError` envelope with a code from a fixed
    16-code taxonomy, so a client maps errors once.

    - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward
    `cursor`; `page_size: 0` returns counts only.

    - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`)
    travel as JSON text and array-valued ones repeat as `name[]=value`.

    - The MCP-only `_meta` field (usage analytics) never reaches the backend and
    is not part of this contract.
  version: '1.0'
  contact:
    name: GetSales
    url: https://getsales.io
    email: support@getsales.io
  license:
    name: Proprietary
    url: https://getsales.io/terms
servers:
  - url: https://beta.getsales.io/id/v1
    description: >-
      Production (the gateway path on the beta ring; the origin is provisioned
      per DEPLOY_MAP.md)
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: api_keys
    description: Registry package `mcp.id/api_keys`, served on MCP mount `id.access`.
  - name: billing_payment_methods
    description: >-
      Registry package `mcp.id/billing_payment_methods`, served on MCP mount
      `id.billing`.
  - name: billing_products
    description: >-
      Registry package `mcp.id/billing_products`, served on MCP mount
      `id.billing`.
  - name: billing_subscriptions
    description: >-
      Registry package `mcp.id/billing_subscriptions`, served on MCP mount
      `id.billing`.
  - name: billing_transactions
    description: >-
      Registry package `mcp.id/billing_transactions`, served on MCP mount
      `id.billing`.
  - name: credit_lots
    description: Registry package `mcp.id/credit_lots`, served on MCP mount `id.billing`.
  - name: credit_transactions
    description: >-
      Registry package `mcp.id/credit_transactions`, served on MCP mount
      `id.billing`.
  - name: gtm_connections
    description: >-
      Registry package `mcp.id/gtm_connections`, served on MCP mount
      `id.identity`.
  - name: notifications
    description: >-
      Registry package `mcp.id/notifications`, served on MCP mount
      `id.notifications`.
  - name: oauth_authorizations
    description: >-
      Registry package `mcp.id/oauth_authorizations`, served on MCP mount
      `id.access`.
  - name: oauth_clients
    description: Registry package `mcp.id/oauth_clients`, served on MCP mount `id.access`.
  - name: sessions
    description: Registry package `mcp.id/sessions`, served on MCP mount `id.identity`.
  - name: ssl_certificates
    description: >-
      Registry package `mcp.id/ssl_certificates`, served on MCP mount
      `id.partner`.
  - name: subscription_allocations
    description: >-
      Registry package `mcp.id/subscription_allocations`, served on MCP mount
      `id.partner`.
  - name: team_members
    description: Registry package `mcp.id/team_members`, served on MCP mount `id.identity`.
  - name: teams
    description: Registry package `mcp.id/teams`, served on MCP mount `id.identity`.
  - name: user_profiles
    description: >-
      Registry package `mcp.id/user_profiles`, served on MCP mount
      `id.identity`.
  - name: users
    description: Registry package `mcp.id/users`, served on MCP mount `id.identity`.
  - name: whitelabel_clients
    description: >-
      Registry package `mcp.id/whitelabel_clients`, served on MCP mount
      `id.partner`.
  - name: whitelabels
    description: Registry package `mcp.id/whitelabels`, served on MCP mount `id.partner`.
  - name: workspace_profiles
    description: >-
      Registry package `mcp.id/workspace_profiles`, served on MCP mount
      `id.identity`.
paths:
  /api/whitelabels/{sid}:
    patch:
      tags:
        - whitelabels
      summary: Update whitelabel
      description: >-
        Rebrand: name, the artwork URLs, the palette and the email chrome,
        effective on the next app load and the next email. domain changes only
        while pending_domain (422 on a live brand: disable and create anew). A
        new email_from_address on another domain drops the old proof: verify it
        again. At least one field, else 422 nothing_to_update.


        Contract:

        - MCP tool `update_whitelabel`, registry package `mcp.id/whitelabels`,
        mount `id.partner`.

        - Operation `update`, response envelope `update`.

        - Flags: none.
      operationId: update_whitelabel
      parameters:
        - name: sid
          in: path
          required: true
          description: Whitelabel (brand) sid (id_wl_...).
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^id_wl_
            description: Whitelabel (brand) sid (id_wl_...).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWhitelabelRequest'
      responses:
        '200':
          description: '`update` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateWhitelabelResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    UpdateWhitelabelRequest:
      type: object
      description: Request body of `update_whitelabel`.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: New brand name, 1..255 chars.
        domain:
          type: string
          maxLength: 253
          pattern: ^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$
          description: New host, only while the brand is pending_domain.
        logo_url:
          type: string
          nullable: true
          maxLength: 2048
          pattern: ^https:\/\/
          description: >-
            https URL of the horizontal logo; null clears it. The file itself is
            uploaded in the app.
        icon_url:
          type: string
          nullable: true
          maxLength: 2048
          pattern: ^https:\/\/
          description: https URL of the square mark; null clears it.
        login_image_url:
          type: string
          nullable: true
          maxLength: 2048
          pattern: ^https:\/\/
          description: https URL of the login artwork; null clears it.
        palette:
          type: object
          nullable: true
          properties:
            primary_color:
              type: string
              nullable: true
              pattern: ^#[0-9a-fA-F]{6}$
              description: 'Buttons and links, #rrggbb; null = the platform default.'
            accent_color:
              type: string
              nullable: true
              pattern: ^#[0-9a-fA-F]{6}$
              description: 'The accent, #rrggbb; null = the platform default.'
            login_background_color:
              type: string
              nullable: true
              pattern: ^#[0-9a-fA-F]{6}$
              description: 'The login page background, #rrggbb; null = the platform default.'
          description: 'Brand colors, #rrggbb each; null = the platform defaults.'
        email_from_name:
          type: string
          nullable: true
          maxLength: 255
          description: The From name on the clients' mail; null = the brand name.
        email_reply_to:
          type: string
          nullable: true
          maxLength: 255
          format: email
          description: The Reply-To on the clients' mail; null = none.
        email_from_address:
          type: string
          nullable: true
          maxLength: 255
          format: email
          description: >-
            The brand's own sender address; refused on a host SendGrid cannot
            authenticate (422 email_domain_invalid), a platform domain (422
            email_domain_reserved) or another team's (409
            email_domain_already_taken). Proven by
            verify_whitelabel_email_domain.
    UpdateWhitelabelResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - update
        item:
          type: object
          properties:
            sid:
              type: string
              description: Brand sid (id_wl_...).
            team_sid:
              type: string
              description: The owning reseller team (ts_tm_...).
            name:
              type: string
              description: The brand name the app shell shows and the mail is signed with.
            domain:
              type: string
              description: >-
                The app and login host (app.reseller.com), lowercase FQDN,
                unique platform-wide; read-only once active.
            status:
              type: string
              enum:
                - pending_domain
                - active
                - disabled
              description: >-
                pending_domain = waiting for the CNAME and the certificate;
                active = the host serves the brand; disabled = switched off, the
                host falls back to the platform brand.
            logo_url:
              type: string
              nullable: true
              description: The horizontal logo (app shell and email header).
            icon_url:
              type: string
              nullable: true
              description: The square mark or favicon.
            login_image_url:
              type: string
              nullable: true
              description: The login page artwork.
            palette:
              type: object
              nullable: true
              properties:
                primary_color:
                  type: string
                  nullable: true
                  pattern: ^#[0-9a-fA-F]{6}$
                  description: 'Buttons and links, #rrggbb; null = the platform default.'
                accent_color:
                  type: string
                  nullable: true
                  pattern: ^#[0-9a-fA-F]{6}$
                  description: 'The accent, #rrggbb; null = the platform default.'
                login_background_color:
                  type: string
                  nullable: true
                  pattern: ^#[0-9a-fA-F]{6}$
                  description: >-
                    The login page background, #rrggbb; null = the platform
                    default.
              description: Brand colors; null = all platform defaults.
            email_from_name:
              type: string
              nullable: true
              description: The From name on the clients' mail; null = the brand name.
            email_reply_to:
              type: string
              nullable: true
              description: The Reply-To on the clients' mail; null = none.
            email_from_address:
              type: string
              nullable: true
              description: >-
                The brand's own sender address; mail leaves from it once
                email_domain is verified, from the platform address under the
                brand's name until then.
            email_domain:
              type: object
              nullable: true
              properties:
                domain:
                  type: string
                  description: >-
                    The domain part of email_from_address, lowercase: what
                    SendGrid authenticates.
                status:
                  type: string
                  enum:
                    - pending
                    - verified
                    - failed
                  description: >-
                    pending = records not all found yet; verified = the brand's
                    mail leaves from its own address; failed = see
                    failure_reason.
                records:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        description: >-
                          cname (three of them: the return path and two DKIM
                          keys).
                      host:
                        type: string
                        description: The record name to publish at the domain's DNS host.
                      value:
                        type: string
                        description: The CNAME target at SendGrid.
                      valid:
                        type: boolean
                        description: What the last check found for this record.
                    required:
                      - type
                      - host
                      - value
                      - valid
                  description: >-
                    The DNS records to publish, in the order SendGrid issued
                    them.
                failure_reason:
                  type: string
                  nullable: true
                  enum:
                    - email_domain_rejected
                    - email_domain_not_proven_in_time
                  description: >-
                    email_domain_rejected (SendGrid refused the domain) or
                    email_domain_not_proven_in_time (48 hours lapsed); null
                    unless failed.
                checked_at:
                  type: string
                  nullable: true
                  description: ISO 8601 UTC of the last check against SendGrid.
                verified_at:
                  type: string
                  nullable: true
                  description: >-
                    ISO 8601 UTC since when it is verified; null while it is
                    not.
              required:
                - domain
                - status
                - records
                - failure_reason
                - checked_at
                - verified_at
              description: >-
                The proof of the sending domain; null = verify never ran, or the
                address moved to another domain.
            created_by:
              type: object
              properties:
                actor_type:
                  type: string
                  enum:
                    - user
                    - support
                    - api_key
                    - system
                    - agent
                actor_sid:
                  type: string
                  nullable: true
                team_sid:
                  type: string
                actor_name:
                  type: string
                  nullable: true
                  description: >-
                    The OAuth client that acted ("Claude", "n8n"); null for a
                    user, an API key or a system job.
                oauth_client_sid:
                  type: string
                  nullable: true
                  description: The acting OAuth client (id_oc_*); null off the OAuth path.
                reason:
                  type: string
                  nullable: true
                  description: >-
                    Why a system actor wrote the row (snapshot_capture_job,
                    ...); null otherwise.
                permissions:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Internal audit context: the grant set the actor held at
                    write time. Not a contract.
                cluster_id:
                  type: integer
                  nullable: true
                  description: 'Internal audit context: the cluster that served the write.'
                trace_id:
                  type: string
                  nullable: true
                  description: >-
                    Internal audit context: the trace id of the request that
                    wrote the row.
              required:
                - actor_type
                - actor_sid
                - team_sid
                - permissions
              description: Who registered the brand.
            created_at:
              type: string
              description: ISO 8601 UTC.
            updated_at:
              type: string
              description: ISO 8601 UTC.
            deleted_at:
              type: string
              nullable: true
              description: ISO 8601 UTC; null = live.
          required:
            - sid
            - team_sid
            - name
            - domain
            - status
            - logo_url
            - icon_url
            - login_image_url
            - palette
            - email_from_name
            - email_reply_to
            - email_from_address
            - email_domain
            - created_by
            - created_at
            - updated_at
            - deleted_at
        updated_fields:
          type: array
          items:
            type: string
        previous_values:
          type: object
          additionalProperties: {}
        kept_fields:
          type: array
          items:
            type: string
          description: >-
            The fields this write did not change because the person's own value
            stands on them (stamped person); read the item for what landed.
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - operation
        - item
        - updated_fields
        - previous_values
        - meta
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
                - nothing_to_update
                - not_found
                - relation_not_found
                - invalid_transition
                - limit_exceeded
                - payment_required
                - duplicate_rejected
                - conflict
                - delete_blocked
                - unauthorized
                - forbidden
                - rate_limited
                - internal_error
                - service_unavailable
                - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    rule:
                      type: string
                    message:
                      type: string
                  required:
                    - rule
                    - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: >-
                      Machine-readable blocker type (active_flow, pending_tasks,
                      …).
                  severity:
                    type: string
                    enum:
                      - hard
                      - soft
                    description: >-
                      hard = external action required; soft = acknowledge is
                      enough.
                  description:
                    type: string
                  entity_sid:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                  - type
                  - severity
                  - description
                  - entity_sid
                  - resolution
                  - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
            - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - error
  responses:
    McpClientError:
      description: >-
        MCP error envelope. `error.code` is one of validation_failed,
        nothing_to_update, not_found, relation_not_found, invalid_transition,
        limit_exceeded, payment_required, duplicate_rejected, conflict,
        delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gs.service.id. Its `access_identity` claim
        carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is
        authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: >-
        Team scope for tokens that do not carry one. Ignored when the token
        already names a team.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.