---
title: "Activate whitelabel"
method: POST
path: "/api/whitelabels/{sid}/activate"
tags: ["whitelabels"]
---

# Activate whitelabel

`POST /api/whitelabels/{sid}/activate`

## Request

- Base URL: `https://beta.getsales.io/id/v1`
- URL: `https://beta.getsales.io/id/v1/api/whitelabels/{sid}/activate`
- Auth: HTTP bearer and API key in header `Team-SID`

Start or retry proving the brand's domain: the certificate row is ensured and a job issues it over ACME HTTP-01, retrying while the DNS propagates (about a day at most); on success the brand flips pending_domain to active. ASYNC: tell the reseller to point the domain's CNAME at the platform, then poll get_whitelabel with include ssl_certificate until status is active (or the certificate's last_error names the fault: domain_not_pointed, domain_validation_failed). Idempotent while pending; a no-op on an active brand; 404 on a deleted one.

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

## Path parameters

- `sid` string, required: Whitelabel (brand) sid (id_wl_...).

## Response `200`

`action_async` success envelope.

- ActivateWhitelabelResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required
  - `async` true, required
  - `item` object, nullable, required
    - `sid` string, required: Brand sid (id_wl_...).
    - `team_sid` string, required: The owning reseller team (ts_tm_...).
    - `name` string, required: The brand name the app shell shows and the mail is signed with.
    - `domain` string, required: The app and login host (app.reseller.com), lowercase FQDN, unique platform-wide; read-only once active.
    - `status` 'pending_domain' | 'active' | 'disabled', required: 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` string, nullable, required: The horizontal logo (app shell and email header).
    - `icon_url` string, nullable, required: The square mark or favicon.
    - `login_image_url` string, nullable, required: The login page artwork.
    - `palette` object, nullable, required: Brand colors; null = all platform defaults.
      - `primary_color` string, nullable: Buttons and links, #rrggbb; null = the platform default.
      - `accent_color` string, nullable: The accent, #rrggbb; null = the platform default.
      - `login_background_color` string, nullable: The login page background, #rrggbb; null = the platform default.
    - `email_from_name` string, nullable, required: The From name on the clients' mail; null = the brand name.
    - `email_reply_to` string, nullable, required: The Reply-To on the clients' mail; null = none.
    - `email_from_address` string, nullable, required: 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` object, nullable, required: The proof of the sending domain; null = verify never ran, or the address moved to another domain.
      - `domain` string, required: The domain part of email_from_address, lowercase: what SendGrid authenticates.
      - `status` 'pending' | 'verified' | 'failed', required: pending = records not all found yet; verified = the brand's mail leaves from its own address; failed = see failure_reason.
      - `records` object[], required: The DNS records to publish, in the order SendGrid issued them.
        - `type` string, required: cname (three of them: the return path and two DKIM keys).
        - `host` string, required: The record name to publish at the domain's DNS host.
        - `value` string, required: The CNAME target at SendGrid.
        - `valid` boolean, required: What the last check found for this record.
      - `failure_reason` 'email_domain_rejected' | 'email_domain_not_proven_in_time', nullable, required: email_domain_rejected (SendGrid refused the domain) or email_domain_not_proven_in_time (48 hours lapsed); null unless failed.
      - `checked_at` string, nullable, required: ISO 8601 UTC of the last check against SendGrid.
      - `verified_at` string, nullable, required: ISO 8601 UTC since when it is verified; null while it is not.
    - `created_by` object, required: Who registered the brand.
      - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required
      - `actor_sid` string, nullable, required
      - `team_sid` string, required
      - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job.
      - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path.
      - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise.
      - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract.
      - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write.
      - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row.
    - `created_at` string, required: ISO 8601 UTC.
    - `updated_at` string, required: ISO 8601 UTC.
    - `deleted_at` string, nullable, required: ISO 8601 UTC; null = live.
  - `pending` object[], required: One ref: the proof in flight.
    - `expected_completion_seconds` integer, required: activate: 300; verify-email-domain: 3600.
    - `webhook_events` string[], required: activate: whitelabels.activated, whitelabels.activation-failed; verify-email-domain: whitelabels.email-domain-verified, whitelabels.email-domain-failed.
    - `polling_hint` string, required: Poll get_whitelabel: after activate (include ssl_certificate) until status is active; after verify-email-domain until email_domain.status is verified or failed.
  - `result` object, required
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: 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` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: 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.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/revisions/95e48541fe85?raw)