# Connect a provider account with a key

> Connect a provider account with a key: CustomDomain™ API reference in the provider accounts group. Covers parameters, request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/provider-accounts/createProviderAccount

## `POST https://api.customdomain.ai/v1/provider-accounts`

Keeps a DNS provider or registrar key for the workspace, encrypted (`503` when keys cannot be kept). The key is checked first by listing the provider's domains, or, for a provider that cannot list them, by reading one of the selected domains or `check_domain`; with neither, `400` `check_domain_required`, and a key is never kept unchecked. `access` is `continuous` (kept until revoked, used only to put back records it wrote that disappear where the deployment has automatic repair on, remove records when a domain is removed, and re-apply the records it wrote on request) or `one_time` (usable for an hour, and deleted as soon as the chosen domains are connected or the hour passes). `scope` is `all` of the account's domains or `selected` ones. The key is never returned.

A provider whose credential is a login or a short lived token (ALL-INKL, Arsys, Azure DNS, Binary Lane, Google Cloud DNS, INWX, Loopia, Openprovider, Plesk, Subreg) is used once and never kept: `access` defaults to `one_time` for it, and `continuous` answers `422` `use_once_credential`.

Anyone whose role operates applications may connect a key and read the accounts. Renaming an account, changing its access, scope or domains, listing the domains its key reaches, connecting domains with it, replacing its key, renewing it by signing in again, checking it and removing it take an admin, an owner or the member who connected it (`can_manage`); a key a customer's sign-in made, which no member connected, is managed by an admin or an owner alone. Every change, every Check now (`provider_account.checked`) and every call that connects domains (`provider_account.domains_connected`) is recorded in the audit log (`provider_account.*`, `GET /audit`).

### Authentication

`apiKey`

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | yes |  |
| `label` | string | no |  |
| `access` | `continuous`, `one_time` | no | `one_time` is the default, and the only access, for a provider whose credential is used once and never kept. |
| `scope` | `all`, `selected` | no |  |
| `domains` | array of string | no |  |
| `check_domain` | string | no | A domain the key manages, read to check the key when the provider cannot list its domains and `scope` is `all`. |
| `credential` | object | yes |  |

### Responses

| Status | Description |
| --- | --- |
| `201` | The account, and the provider's domains when it lists them |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `403` | Error envelope: {code, title, details}. |
| `422` | The provider refused the key (`ProviderAuthenticationError`), or `continuous` access for a credential that is used once and never kept (`use_once_credential`), or a chosen Porkbun domain is not opted in to API access (`porkbun_api_access_disabled`, where `400` would otherwise say the key does not reach it) |
| `503` | Error envelope: {code, title, details}. |

### `201` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | object | no |  |
| `zones` | array of string | no |  |

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