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.
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.
Authorization
apiKey Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/provider-accounts/string" \ -H "Content-Type: application/json" \ -d '{}'{ "account": { "needs_you": { "reason": "refused", "until": "2019-08-24T14:15:22Z" }, "health": { "state": "ok", "checked_at": "2019-08-24T14:15:22Z", "failures": 0 }, "made_by": { "how": "pasted", "by": "string" }, "enforced_by": "provider", "more_domains": [ "string" ], "id": "string", "kind": "api_key", "provider": "string", "provider_name": "string", "label": "string", "access": "continuous", "scope": "all", "domains": [ "string" ], "credential_held": true, "status": "active", "last_error": "string", "created_by": "string", "last_used_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "connections": [ { "id": "string", "application_id": "string", "domain": "string", "status": "string" } ], "uses": [ "string" ], "can_manage": true, "application_id": "string", "application_ids": [ "string" ], "origin": "browser_agent", "agent_key": { "name": "string", "scopes": [ "string" ], "account": "string", "session_id": "string", "verified_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "notice": "d30", "reconnect_reason": "expiring", "reconnect_sent_at": "2019-08-24T14:15:22Z", "renewed_at": "2019-08-24T14:15:22Z", "old_key": "revoke_by_hand", "revoke_url": "http://example.com", "rights": [ "transfer" ] }, "owner_kind": "workspace", "end_user_ref": "string", "account_ref": "string" }}{ "code": "account_not_verifiable", "title": "string", "details": "string", "challenge": { "value": "string", "bits": 1, "expires_at": "2019-08-24T14:15:22Z" }}{ "code": "account_not_verifiable", "title": "string", "details": "string", "challenge": { "value": "string", "bits": 1, "expires_at": "2019-08-24T14:15:22Z" }}{ "code": "account_not_verifiable", "title": "string", "details": "string", "challenge": { "value": "string", "bits": 1, "expires_at": "2019-08-24T14:15:22Z" }}{ "code": "account_not_verifiable", "title": "string", "details": "string", "challenge": { "value": "string", "bits": 1, "expires_at": "2019-08-24T14:15:22Z" }}{ "code": "account_not_verifiable", "title": "string", "details": "string", "challenge": { "value": "string", "bits": 1, "expires_at": "2019-08-24T14:15:22Z" }}{ "code": "account_not_verifiable", "title": "string", "details": "string", "challenge": { "value": "string", "bits": 1, "expires_at": "2019-08-24T14:15:22Z" }, "domains": [ "string" ]}{ "code": "reach_quota", "title": "Too many checks at DNS providers this hour.", "details": "this workspace has made as many checks of its keys at DNS providers as it may in an hour; nothing was changed, try again in about 40 minutes"}{ "code": "account_not_verifiable", "title": "string", "details": "string", "challenge": { "value": "string", "bits": 1, "expires_at": "2019-08-24T14:15:22Z" }}