# RevCent MCP Guide: `InitializeTrackingDomainSSL`

AI/MCP-focused guide for initializing SSL for a RevCent Tracking Domain.

This document explains the `InitializeTrackingDomainSSL` operation, why it exists, when to run it, required prerequisites, expected output, CNAME record handling, status values, and how it fits into the full Tracking Domain DNS setup lifecycle.

---

## Related Documentation

AI/MCP clients should also read these related files:

| Operation / Overview | Link | Why It Matters |
|---|---|---|
| Tracking Domain Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTrackingDomain.md` | Broad context for Tracking Domains, DNS tracking, visitor attribution, URL parameters, metadata, Track.js, WooCommerce tracking, and reporting. |
| CreateTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/CreateTrackingDomain.md` | Explains the full setup lifecycle: create domain, add A records, initialize SSL, add CNAME records, initialize DNS. |
| GetTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/GetTrackingDomain.md` | Retrieves A records, SSL status, CNAME records, DNS status, and current Tracking Domain configuration. |
| InitializeTrackingDomainSSL | `https://revcent.com/documentation/markdown/mcp/operation/InitializeTrackingDomainSSL.md` | Initializes SSL and returns required CNAME records. |
| InitializeTrackingDomainDNS | `https://revcent.com/documentation/markdown/mcp/operation/InitializeTrackingDomainDNS.md` | Completes DNS tracking setup after A records, SSL, and CNAME records are ready. |
| EditTrackingDomain | `https://revcent.com/documentation/markdown/mcp/operation/EditTrackingDomain.md` | Edits name, description, URL Parameter Sets, or legacy URL parameters. |
|


---

## Operation Summary

Operation:

```text
InitializeTrackingDomainSSL
```

Title:

```text
Initialize SSL for A Tracking Domain
```

Purpose:

```text
Initialize SSL for a specific Tracking Domain using the Tracking Domain ID.
```

This operation starts the SSL issuance process for a Tracking Domain.

It should be run after:

```text
CreateTrackingDomain
    ↓
Add required A records to the domain's DNS
    ↓
InitializeTrackingDomainSSL
```

The operation returns SSL status information and the required DNS CNAME records that must be added to the domain's DNS to complete SSL validation.

---

## Why SSL Initialization Is Required

A Tracking Domain must have valid SSL before DNS tracking can be completed and used reliably.

SSL is required because RevCent Tracking Domains support browser-facing tracking endpoints and first-party tracking behavior. A valid SSL certificate allows these endpoints to work securely over HTTPS.

Simple purpose:

```text
InitializeTrackingDomainSSL = start SSL certificate validation and retrieve CNAME records
```

After SSL is issued, the Tracking Domain can proceed to DNS initialization.

---

## Correct Setup Sequence

The correct Tracking Domain setup sequence is:

```text
1. CreateTrackingDomain
2. Add returned A records to DNS
3. InitializeTrackingDomainSSL
4. Add returned CNAME records to DNS
5. Wait until ssl.status = ISSUED
6. InitializeTrackingDomainDNS
7. Confirm dns.status = COMPLETE
```

Important:

```text
Do not run InitializeTrackingDomainDNS before SSL is issued.
```

`InitializeTrackingDomainSSL` happens before `InitializeTrackingDomainDNS`.

---

## Prerequisites

Before calling `InitializeTrackingDomainSSL`, verify:

- a Tracking Domain already exists,
- `tracking_domain_id` is known,
- the user owns/controls the root domain DNS,
- A records from `CreateTrackingDomain` or `GetTrackingDomain` have been added to the domain's DNS,
- enough DNS propagation time has passed if records were just added,
- the user understands CNAME records will be returned and must also be added.

The live operation instructions state that the A records supplied when the tracking domain was created must be added before running SSL initialization.

Use:

```text
GetTrackingDomain
```

to retrieve A records if they are needed again.

---

## Input Schema

`InitializeTrackingDomainSSL` requires:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `tracking_domain_id` | string | Yes | 20-character Tracking Domain ID. |

Example request:

```json
{
  "tracking_domain_id": "TTTTTTTTTTTTTTTTTTTT"
}
```

Only send supported fields.

---

## Output Schema

Successful output can include:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | API response code. `1` indicates success. |
| `tracking_domain_id` | string | 20-character Tracking Domain ID. |
| `a_records` | array | A records required for DNS setup. |
| `ssl.status` | string | Current SSL status. |
| `ssl.cname_records` | array | CNAME records that must be added to DNS for SSL issuance. |
| `result` | string | Result message. |

The most important output after calling this operation is:

```text
ssl.cname_records
```

Those CNAME records must be added to the user's domain DNS.

---

## CNAME Records

`InitializeTrackingDomainSSL` returns CNAME records inside:

```text
ssl.cname_records
```

Each record includes:

| Field | Meaning |
|---|---|
| `name` | CNAME record name/host. |
| `value` | CNAME record target/value. |

Example shape:

```json
{
  "ssl": {
    "status": "PENDING_VALIDATION",
    "cname_records": [
      {
        "name": "example-cname-name",
        "value": "example-cname-value"
      }
    ]
  }
}
```

The user must add each CNAME record exactly as returned.

Do not modify:

- record names,
- record values,
- record type,
- hostname structure,
- target values.

Some DNS providers automatically append the root domain to record names. AI/MCP should warn users to follow their DNS provider's conventions while preserving the returned record values exactly.

---

## SSL Status Values

SSL status can be:

| Status | Meaning | AI/MCP Guidance |
|---|---|---|
| `NOT_INITIALIZED` | SSL setup has not started. | Run `InitializeTrackingDomainSSL` after A records are added. |
| `PENDING_VALIDATION` | SSL initialization started and RevCent is waiting for CNAME verification. | Add/verify CNAME records and allow DNS propagation. |
| `VALIDATION_TIMED_OUT` | RevCent timed out waiting for CNAME validation. | Verify CNAME records, DNS propagation, and retry/reset flow where applicable. |
| `ISSUED` | CNAME records were verified and SSL certificate was issued. | Proceed to `InitializeTrackingDomainDNS`. |
| `FAILED` | SSL issuance failed. | Verify DNS records and use the reset/retry operation where available. |

Do not proceed to DNS initialization until:

```text
ssl.status = ISSUED
```

---

## Recommended AI/MCP Workflow

```text
1. User asks to initialize SSL for a Tracking Domain.
2. Use GetTrackingDomain to retrieve current status.
3. Confirm A records are available and already added to DNS.
4. If A records are not added, show the user the A records and have them add them first.
5. After user confirms A records are added, call InitializeTrackingDomainSSL.
6. Capture returned ssl.cname_records.
7. Show the CNAME records to the user.
8. Instruct the user to add each CNAME record to DNS.
9. Use GetTrackingDomain to check ssl.status.
10. When ssl.status = ISSUED, proceed to InitializeTrackingDomainDNS.
```

---

## When Not to Run

Do not run `InitializeTrackingDomainSSL` when:

- the Tracking Domain has not been created,
- `tracking_domain_id` is unknown,
- the user has not added the required A records,
- the user does not control DNS,
- the wrong root domain was created,
- the user is trying to edit name/description/URL parameters,
- the user is trying to report on attribution/metadata.

Use `CreateTrackingDomain` first when no Tracking Domain exists.

Use `EditTrackingDomain` for editable configuration changes.

Use BigQuery for reporting.

---

## Example: Correct SSL Initialization Flow

```text
Tracking Domain created
    ↓
GetTrackingDomain retrieves A records
    ↓
User adds A records:
        rctrk
        portal
        rcacp
    ↓
User confirms A records added
    ↓
InitializeTrackingDomainSSL
    ↓
Response returns ssl.cname_records
    ↓
User adds CNAME records
    ↓
GetTrackingDomain confirms ssl.status = ISSUED
    ↓
InitializeTrackingDomainDNS
```

---

## DNS Provider Guidance

When instructing the user to add CNAME records, explain common DNS fields:

| DNS Field | Value |
|---|---|
| Type | `CNAME` |
| Name / Host | `name` from `ssl.cname_records` |
| Value / Target / Points To | `value` from `ssl.cname_records` |
| TTL | Default/automatic is usually acceptable unless user has a reason to change it. |

Important:

```text
Use exact values returned by RevCent.
Do not invent or normalize CNAME values.
```

---

## Troubleshooting

### SSL Remains `PENDING_VALIDATION`

Possible causes:

- CNAME records not added,
- CNAME records added incorrectly,
- DNS provider appended root domain unexpectedly,
- DNS propagation delay,
- conflicting DNS records,
- A records missing or incorrect.

Recommended steps:

```text
1. Use GetTrackingDomain to retrieve CNAME records.
2. Have user verify records in DNS provider.
3. Confirm record type is CNAME.
4. Confirm name and value match RevCent response.
5. Wait for DNS propagation.
6. Check GetTrackingDomain again.
```

### SSL Becomes `VALIDATION_TIMED_OUT`

Recommended steps:

```text
1. Verify CNAME records exactly.
2. Verify A records are still correct.
3. Check for DNS provider formatting issues.
4. Use reset/retry operation if available.
```

### SSL Becomes `FAILED`

Recommended steps:

```text
1. Verify A and CNAME records.
2. Confirm domain ownership/control.
3. Check for conflicting records.
4. Use reset/retry process where available.
```

---

## Best Practices

1. Always retrieve the Tracking Domain before SSL initialization.
2. Confirm A records are added before running the operation.
3. Show the user the exact CNAME records returned.
4. Tell the user not to modify record names or values.
5. Use `GetTrackingDomain` to check `ssl.status` after CNAME records are added.
6. Do not proceed to DNS initialization until SSL is `ISSUED`.
7. Keep the setup sequence clear: A records first, SSL second, CNAME records third, DNS initialization fourth.
8. Use the Tracking Domain overview for broader tracking context.
9. Use `CreateTrackingDomain.md` for complete setup lifecycle context.

---

## Common Mistakes to Avoid

Do not:

- run SSL initialization before A records are added,
- skip showing CNAME records to the user,
- proceed to DNS initialization before SSL is issued,
- assume DNS propagation is immediate,
- modify CNAME names or values,
- confuse A records with CNAME records,
- attempt to change the root domain during SSL setup,
- use this operation for URL parameter configuration,
- call the Tracking Domain DNS-ready before `ssl.status = ISSUED` and `dns.status = COMPLETE`.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Start SSL setup | Use `InitializeTrackingDomainSSL` after A records are added. |
| Retrieve required A records | Use `GetTrackingDomain`. |
| Retrieve returned CNAME records | Use `InitializeTrackingDomainSSL` response or `GetTrackingDomain`. |
| Check SSL status | Use `GetTrackingDomain`. |
| SSL is issued | Proceed to `InitializeTrackingDomainDNS`. |
| DNS tracking setup complete | Confirm `dns.status = COMPLETE` with `GetTrackingDomain`. |
| Change name/URL parameters | Use `EditTrackingDomain`. |
| Create a Tracking Domain | Use `CreateTrackingDomain`. |

---

## Final AI/MCP Instruction

Use `InitializeTrackingDomainSSL` after the Tracking Domain has been created and the required A records have been added to the root domain's DNS.

The operation starts SSL validation and returns CNAME records in `ssl.cname_records`. The user must add those CNAME records to DNS. After the CNAME records are validated and `ssl.status = ISSUED`, proceed to `InitializeTrackingDomainDNS` to complete DNS tracking setup.

Do not run `InitializeTrackingDomainDNS` before SSL is issued.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.