# Change an account's label, access, scope or the applications it is shared with

> update provider account: 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/updateProviderAccount

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

Narrowing the scope detaches the domains it no longer covers; they stay connected, without continuous access. Switching to `one_time` deletes the key now. Switching to `continuous` needs the key still held. Changing the `label`, `access`, `scope` or `domains` takes whoever manages the account: an admin, an owner or the member who connected it (`403` otherwise, with nothing stored and nothing audited); for a key an end user's own sign-in made, which no member connected, an admin or an owner alone. A `label` is one to 80 characters once trimmed (spaces, line breaks and the byte order mark at its ends are removed), counted in characters, and holds no control or invisible character: no NUL, tab or line break, zero width space, byte order mark or text direction override (`400` `invalid_request` otherwise, and nothing in the call is stored). `continuous` access for a credential that is used once and never kept answers `422` `use_once_credential`. A change is recorded in the audit log (`provider_account.updated`, with the label, access, scope, domains and applications before and after).

What each kind of account allows when `scope` or `domains` widens it (`made_by.how` names the kind). Narrowing and renaming ask nothing of the provider, for every kind, with one exception: a key made at a secure sign-in that goes from `all` back to `selected` has each domain it names that the account does not already hold read first (at most 20 a call, `400` `too_many_domains_to_check` beyond). A change that is refused stores nothing.

`pasted`: any scope and any domains. The person chose the key and what it is used for, so nothing is read at the provider; connecting a domain the key cannot write is what finds it.

`console_sign_in`, a key made at a secure sign-in a member started in the console: it widens only to domains the key reaches at the provider. Each domain added is read with the key, by its zone, before anything is stored. A call that names a domain the key does not reach answers `422` `zone_not_reached`, naming those domains in `domains`, and stores nothing, not even the domains that were reached. A failure that says nothing about the key (a timeout, a `5xx`) answers `503` and stores nothing. At most 20 new domains are read in one call (`400` `too_many_domains_to_check`), and an account that no longer holds its key answers `409`. Setting `scope` to `all` has no domain to read, so it needs the provider to list the domains a key reaches and this key to list them now: a provider that cannot answers `422` `scope_all_needs_list` (add the domains instead), and a key the provider refuses answers `422` `ProviderAuthenticationError`. The scope `all` is no way round the read of a domain: while it is `all`, a domain named that the account does not already hold in `domains` is read too, whether the call keeps `all` or goes back to `selected`. The change is written on the account as it is after the reads, so a renewal that landed meanwhile is kept; an account that lost its key, or whose change no longer matches what was read, answers `409` and nothing is written.

Those reads (one for each new domain's zone, and the list the scope `all` needs) are taken from the workspace's hourly budget of reach checks; a zone whose answer CustomDomain™ kept from a read in the last ten minutes costs none. A change whose reads do not fit in what is left of the hour answers `429` `reach_quota` with `Retry-After`, reads nothing and writes nothing.

`widget_sign_in`, a key an end user's secure sign-in made in the widget: it is never widened, whoever asks. A change that adds a domain or sets `scope` to `all` answers `403`; renaming, narrowing and removing still work.

`application_ids` is the whole set of other applications of the workspace that may use a key bound to one application, besides its own (`application_id`, which always serves). Sending it replaces the set: name an application to share the key with it, leave it out to take it back, send `[]` to share with none. Naming the key's own application, a repeat or a blank changes nothing. It takes an admin or an owner, never only the member who connected the key (`403` otherwise), and answers `403` for a key an end user's sign-in made, which is never shared, and `404` for an application that is not the workspace's. A key bound to no application already serves every application, so naming one answers `422` `serves_every_application`; at most 100 are taken in a call (`400` beyond). Each application shared is recorded in the audit log as `provider_account.shared`, and each taken out as `provider_account.unshared`, both naming the applications served before and after and the ones changed (`application_ids`). Taking an application out detaches the domains of it that were using the key: they stay connected, without continuous access, and each domain's timeline records `access_revoked` with the reason `unshared`.

### Authentication

`apiKey`

### Parameters

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

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | no | The account's name: one to 80 characters once trimmed, with no control or invisible character in it (`400` `invalid_request` otherwise). Whoever manages the account may change it, as for `access`, `scope` and `domains` (`403` otherwise). |
| `access` | `continuous`, `one_time` | no |  |
| `scope` | `all`, `selected` | no | `all` widens a `selected` account; for a key made at a secure sign-in it needs the provider to list the key's domains (`422` `scope_all_needs_list`). |
| `domains` | array of string | no | The whole set of domains a `selected` account may use. A domain it does not hold yet widens the account; for a key made at a secure sign-in each such domain must be one the key reaches (`422` `zone_not_reached`, at most 20 new ones a call). For an account on `all` that is any domain not already in its `domains`, also when the call goes back to `selected`. |
| `application_ids` | array of string | no | The other applications of the workspace the key is shared with, as a whole: it replaces the set. Admin or owner only. |

### Responses

| Status | Description |
| --- | --- |
| `200` | The account |
| `400` | `invalid_request` (a `label` that is empty once trimmed, longer than 80 characters or holds a control or invisible character, or a change that leaves no domain and no scope `all`) or `too_many_domains_to_check`. Nothing is stored. |
| `401` | Error envelope: {code, title, details}. |
| `403` | `forbidden`: a viewer, or a member who did not connect the account asking to change its `label`, `access`, `scope` or `domains`; anyone but an admin or an owner asking for `application_ids`, or to change a key an end user's sign-in made; or a change that would widen such a key. Nothing is stored and nothing is audited. |
| `404` | Error envelope: {code, title, details}. |
| `409` | Error envelope: {code, title, details}. |
| `422` | `zone_not_reached` (a domain added is not one the key reaches; `domains` names them), `scope_all_needs_list`, `serves_every_application`, `use_once_credential` or `ProviderAuthenticationError`. |
| `429` | `reach_quota`: the workspace has made as many reads at DNS providers, to find out what a key reaches, as it may this hour (the saved key resolver's reads, a key's reach check when its scope is widened, the list of a key's domains and Check now share one budget). Nothing was read at the provider, nothing changed and nothing was spent from the hour. `Retry-After` is the seconds until the hour ends, when the count starts again. |
| `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`.
