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

> start route53 role: reference page for this CustomDomain™ API operation in the connections group. Covers parameters, request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/connections/startRoute53Role

## `POST https://api.customdomain.ai/v1/connections/{id}/route53-role:start`

**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`.

A widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.

### Authentication

`widgetJWT`, `apiKey`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hosted_zone_id` | string | no | 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. |

### Responses

| Status | Description |
| --- | --- |
| `200` | The quick-create link and the steps to show the customer. |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `403` | `forbidden`: the credential may not do this. `workspace_suspended`: see the `ForbiddenOrSuspended` response. `token_wrong_end_user`: a widget token that is not this connection's end user (the connection names another end user than the token's `end_user_ref`, or names one while the token names none); nothing is read, written or changed, and the answer shows nothing of the connection. Mint the token with the end user's `end_user_ref`. |
| `404` | Error envelope: {code, title, details}. |
| `503` | Error envelope: {code, title, details}. |

### `200` response body

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

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.
