# Write a connection's records through the customer's provider (BYO token, used once)

> apply connection: 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/applyConnection

## `POST https://api.customdomain.ai/v1/connections/{id}/apply`

**Rail B (API-token apply).** The scoped provider credential is used once to write the records and is never stored. The connection advances to `propagating`; the poller promotes it to `live` once the records appear in public DNS.

A widget JWT applies to its own application's connections (a domain-bound token to its own domain only). An API key applies to a connection of any application in its tenant; a member's key needs a role that operates apps (not viewer).

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 |
| --- | --- | --- | --- |
| `provider` | string | no | DNS provider id; defaults to the detected provider. |
| `zone` | string | no | DNS zone the credential manages; defaults to the connection domain. |
| `credential` | object | yes |  |
| `records` | array of object | yes |  |

### Responses

| Status | Description |
| --- | --- |
| `200` | Applied |
| `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}. |
| `422` | The provider refused the credential (`ProviderAuthenticationError`) or the write (`dns_write_failed`), or, at Porkbun, the domain is not opted in to API access (`porkbun_api_access_disabled`: the account holder switches on API Access for the domain in Porkbun's Domain Management, then tries again) |
| `503` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connection` | object | no |  |
| `records` | array of object | no |  |

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