---
title: "Start connecting a Route 53 domain through a limited IAM role instead of an access key"
method: POST
path: "/connections/{id}/route53-role:start"
tags: ["Connections"]
---

# Start connecting a Route 53 domain through a limited IAM role instead of an access key

`POST /connections/{id}/route53-role:start`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/connections/{id}/route53-role:start`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

**Route 53 access role.** For a domain whose DNS is in Amazon Route 53, the customer creates a limited IAM role in their own AWS account from the CustomDomain™ CloudFormation template instead of pasting an AWS access key. This call generates the connection's external ID (once: later calls return the same one), stores the hosted zone id when you pass one, and returns a CloudFormation quick-create link plus plain instructions. The role the link creates can be assumed by CustomDomain™ only with that external ID, can read only the chosen hosted zone, and can change only the records for the connected name. Idempotent. Answers `503` when this deployment has not set the rail up. Takes a widget JWT for the connection's own application or an API key for a connection of any application in its tenant (a member's key needs a role that operates apps), like `route53-role:complete`.

## Path parameters

- `id` string, required

## Request body

- object
  - `hosted_zone_id` string: The Route 53 hosted zone that holds the domain, such as `Z23YXV4OVPL04A` (a `/hostedzone/` prefix is accepted). Optional: without it the AWS console lists the account's zones to choose from.

## Response `200`

The quick-create link and the steps to show the customer.

- Route53RoleStart: The answer of `POST /connections/{id}/route53-role:start`.
  - `connection_id` string, required
  - `quick_create_url` string, uri, required: Opens the AWS CloudFormation console with the template and every parameter filled in. Open it in a new tab.
  - `template_url` string, uri, required: The public S3 URL of the CloudFormation template.
  - `region` string, required: The AWS console region the link opens in. IAM roles are global, so it does not limit the role.
  - `stack_name` string, required: The stack name the link proposes.
  - `role_name` string, required: The role the stack creates: CustomDomainDNSAccess- followed by the external ID.
  - `external_id` string, required: The external ID the role requires, generated by CustomDomain™ once per connection. AWS does not treat it as a secret.
  - `trusted_principal_arn` string, required: The CustomDomain™ AWS principal the role trusts.
  - `record_name` string, required: The name the role may change, together with its www name and their verification names.
  - `hosted_zone_id` string: The hosted zone passed to this call, when one was.
  - `role_arn` string: The role already verified for this connection, when there is one.
  - `instructions` string[], required: Plain steps to show the customer.

## Other responses

- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `404`: Error envelope: {code, title, details}.
- `503`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)