# Give an account a new key

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

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

## `POST https://api.customdomain.ai/v1/provider-accounts/{id}/reconnect`

A new key for an account, in one of two ways (`method`). Both take an admin, an owner or the member who connected the account (`403` otherwise), and the key is recorded in the audit log (`provider_account.key_replaced`).

`api_key` (the default), for a key a person pasted: for an account the provider stopped accepting, or a one time account whose key was deleted. Everything is checked before anything is kept: the access mode, then the key (listing the provider's domains, or reading `check_domain`, a selected domain or a domain the account connected, for a provider that cannot list them), and for a `selected` account that the key reaches every selected domain. `params` sent with the key replace the kept ones. A key made at a secure sign-in answers `409`: it is renewed by signing in again, not by pasting a key. `continuous` access (asked, or the account's own) for a credential that is used once and never kept answers `422` `use_once_credential`; send `access` `one_time`.

`secure_sign_in`, for a key made at a secure sign-in a member started in the console: starts the same account sign in as `POST /provider-accounts:sign-in`, for the account's own provider and application, and answers `201` with `session_id` and `popup_url`. The new key swaps into this same account when the person keeps it (`POST /browser-sessions/{sid}:keep` with an empty body), so the account keeps its id, its domains, its scope and the domains linked to it; only its key changes, it is active again with its daily check started afresh, and the key it replaces is named for deletion at the provider (`replaced_key`). It is the console's own call (an API key on the signed visitor forward, `403` `browser_account_unavailable` otherwise) and takes the sign in's body (`return_origin`, `consent_version`, `locale`, `viewport_hint`) and no key. A key a person pasted is renewed by pasting (`409`), and a key a customer's own secure sign-in made is renewed by that customer, never from the console (`403`). The keep refuses a key of another provider account (`422` `different_account`): where the provider names the account, the two must be the same; where it does not (IONOS), the new key must list every domain the account holds. An account that holds no domain and has no account number gives nothing to compare, so its renewal is refused (`422` `account_not_verifiable`): remove the account and add it again with a new sign in. The refused key stays pending and is named for deletion when the sign in is cancelled.

### Authentication

`apiKey`

### Parameters

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

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `method` | `api_key`, `secure_sign_in` | no | How the key is renewed. `api_key` takes `credential` (required then); `secure_sign_in` takes the sign in's fields and no key. |
| `access` | `continuous`, `one_time` | no | `api_key` only. |
| `check_domain` | string | no | `api_key` only: a domain the key manages, read to check the key when the provider cannot list its domains. |
| `credential` | object | no | `api_key` only, and required for it. |
| `return_origin` | string | no | `secure_sign_in` only, required: web origin the popup posts its result to; must be on the server's allowlist. |
| `consent_version` | `cb-1`, `cb-2`, `cb-3`, `cb-4` | no | `secure_sign_in` only, required: the id of the consent text the person was shown, as for `browser:start`. |
| `locale` | string | no | `secure_sign_in` only: the language the popup reads in. Defaults to `en`. |
| `viewport_hint` | object | no | `secure_sign_in` only: the size of the popup's live area, used as for `browser:start`. |

### Responses

| Status | Description |
| --- | --- |
| `200` | The account (`api_key`). |
| `201` | The sign in started (`secure_sign_in`). |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `403` | `forbidden` (a viewer, a member who did not connect the account, or a key a customer's own sign in made, for `secure_sign_in`), `browser_account_unavailable` (`secure_sign_in` from anything but the console's own call), `browser_provider_not_allowed` or `workspace_suspended`. |
| `404` | Error envelope: {code, title, details}. |
| `409` | 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) |
| `429` | Error envelope: {code, title, details}. |
| `503` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | object | no |  |

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