Remove a domain, removing or keeping the DNS records we added
Remove a domain, removing or keeping the DNS records we added: CustomDomain™ API reference. Covers parameters, request body, responses and error codes.
Removes the domain, and with records says what happens to the DNS records we added. remove deletes them and puts back what they replaced, when we know it; keep leaves them. What remove can do depends on how the domain was connected, and GET /connections/{id}/removal says so before you call this: with access we kept (our hosted zone, a kept sign-in, a continuous provider account, a kept Domain Connect authorization) it is automatic; with a one time sign-in or key it needs one more authorization, and this answers 409 reauthorization_required with the plan (sign in again with oauth:start and purpose: "remove", send a key to POST /connections/{id}:disconnect, or call this with records=keep and follow the manual steps); for Domain Connect one-click and manual setups the answer lists the exact manual steps. Records whose value changed since we wrote them, values that were already there before we wrote them, and records another connected domain still uses are never touched. With a key or a sign-in, the zone must show at least one of our records before any record is reported removed or gone; otherwise the answer lists the manual steps (the key may belong to another account).
Whatever the choice, the domain stops being served the moment the removal starts (edges forget it within a minute), its certificate stops renewing and is deleted, its monitoring stops, and connection.disconnected carries a removal object with what happened to the records. GET /connections/{id}/removal answers the same outcome once the connection is gone. A second removal of the same domain while one runs answers 409 removal_in_progress.
Without records the call keeps its original contract: records are taken out only where it always took them out (a kept Domain Connect authorization, a kept sign-in, our hosted zone) and kept otherwise, including with a connected provider account or the Route 53 access role; the answer is 204 with no body. With records the answer is 200 with the outcome.
An end user's widget token (scope connect) must be bound to the domain and, when the connection names an end user, minted with that end_user_ref; otherwise 403.
A delegated agent token needs domains:disconnect, a scope of its own because the removal takes the domain offline, and must send confirm naming the domain. Without it the answer is 400 confirmation_required, and with another domain 409 confirmation_mismatch; nothing is removed either way. Another application's connection answers 404. Any other credential that sends confirm is held to it the same way.
A share link's token (the widget_token of GET /share/{token}) sets a domain up and never removes it: it answers 403 forbidden, on a connection that names an end user or not.
Short-lived widget JWT minted server-side via POST /v1/tokens. Scoped to one application (and optionally one domain).
In: header
Path Parameters
Query Parameters
What to do with the DNS records we added.
Value in
- "remove"
- "keep"
The domain being removed, as written on the connection (case, scheme, path and a trailing dot do not matter). Required of a delegated agent token: without it the answer is 400 confirmation_required. Any credential that sends it, an API key or an application token included, gets 409 confirmation_mismatch when it names another domain (400 confirmation_required when it is empty). Nothing is removed either way. A credential other than an agent token may leave it out.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/connections/string"{ "connection_id": "string", "domain": "string", "disconnected": true, "records": { "choice": "remove", "outcome": "removed", "via": "string", "removed": [ { "type": "string", "name": "string", "value": "string", "note": "string" } ], "restored": [ { "type": "string", "name": "string", "value": "string", "note": "string" } ], "left_in_place": [ { "type": "string", "name": "string", "value": "string", "note": "string" } ], "failed": [ { "type": "string", "name": "string", "value": "string", "note": "string" } ], "manual_steps": [ "string" ] }, "serving": "stopped", "certificate": "removed", "monitoring": "stopped"}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}{ "code": "string", "title": "string", "details": "string"}{ "code": "reauthorization_required", "title": "string", "details": "string", "plan": { "connection_id": "string", "domain": "string", "provider": "string", "provider_name": "string", "connected_via": "string", "access": "kept", "access_detail": "string", "record_removal": "automatic", "default_choice": "remove", "reauthorize": { "methods": [ "sign_in" ], "provider": "string", "flow": "string", "regions": [ "string" ] }, "records_in_use_elsewhere": true, "records": [ { "type": "string", "host": "string", "name": "string", "value": "string", "ttl": 0, "priority": 0, "change": "created", "action": "delete", "prior": [ { "type": "string", "value": "string", "ttl": 0, "priority": 0 } ], "prior_source": "provider", "note": "string" } ], "manual_steps": [ "string" ], "notes": [ "string" ], "teardown": [ "string" ], "removal_started_at": "2019-08-24T14:15:22Z", "removed": true, "removed_at": "2019-08-24T14:15:22Z", "result": { "choice": "remove", "outcome": "removed", "via": "string", "removed": [ { "type": "string", "name": "string", "value": "string", "note": "string" } ], "restored": [ { "type": "string", "name": "string", "value": "string", "note": "string" } ], "left_in_place": [ { "type": "string", "name": "string", "value": "string", "note": "string" } ], "failed": [ { "type": "string", "name": "string", "value": "string", "note": "string" } ], "manual_steps": [ "string" ] } }}