Delete OAuth App API: Delete an OAuth app
The Delete OAuth App API removes a BYOK OAuth app by its ID. Use it when an app is no longer needed, but check first whether any active integrations are still connected under that app, because those integrations depend on it for token refresh and will block deletion until they are disconnected or reconnected.
Delete an OAuth app
Delete an OAuth app when you want to remove a BYOK OAuth app entirely. Deletion is blocked with a 409 response while active integrations are still connected under the app. Those integrations rely on the app for token refresh, so disconnect or reconnect them first and then retry the delete request. Before you call the endpoint, confirm the exact OAuth app ID you intend to remove and confirm that no active integration still needs that app for token refresh. If integrations are still connected, handle that dependency first rather than repeatedly retrying the same delete call.
Authorization and path parameters
Send a DELETE request to {{API_BASE_URL}}/v1/apps/{id}. Authorize the request with the accessKey value in the x-access-key header. The only path parameter is id, a required string described as the OAuth app ID. Replace the id segment with the identifier of the app to delete. This captured reference does not document a request body for the operation. The field map for the request is shown in the Request field map table, and a worked request is shown in the Delete an OAuth app request example.
Response body
A successful deletion returns a 200 response with application/json content. The response body contains success as a required boolean and message as a required string. Treat success as the primary outcome field and message as the accompanying human-readable result. Error responses for 400, 404, and 409 each return application/json with error as a required string. The exact status-to-shape mapping is shown in the Response contract table, and the practical handling for each status is shown in the Failure matrix table.
Failure handling and pre-delete checklist
For a 409 response, do not treat the app as deleted. The blocking condition is that active integrations are still connected under the app and rely on it for token refresh. Disconnect or reconnect those active integrations first, then retry the DELETE request with the same id. For 400 and 404 responses, inspect the error string returned in the response body and verify the request before retrying; the source contract specifies the error shape for these statuses without assigning a more specific cause. Work through the pre-delete checklist in order: confirm the OAuth app ID, check for active integrations, disconnect or reconnect any that remain, send the DELETE request with the x-access-key header, and then check the status and response fields.
| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| id | Path parameter | string | Yes | OAuth app ID |
| x-access-key | Header | string (<token>) | Yes | accessKey authorization header |
Exact preserved contract; origin shown as {{API_BASE_URL}}.
| Status | Content type | Response fields |
|---|---|---|
| 200 | application/json | success: boolean (required); message: string (required) |
| 400 | application/json | error: string (required) |
| 404 | application/json | error: string (required) |
| 409 | application/json | error: string (required) |
Exact preserved contract.
| Status | Meaning | Action |
|---|---|---|
| 200 | App deleted | Read success and message from the response body. |
| 400 | Error response returned | Read error from the response body and verify the request before retrying. |
| 404 | Error response returned | Read error from the response body and verify the request before retrying. |
| 409 | Deletion blocked while active integrations are still connected and rely on the app for token refresh | Disconnect or reconnect the active integrations first, then retry the DELETE request. |
409 meaning and remediation preserved from source; 400 and 404 causes not specified beyond status and error shape.
curl -X DELETE "{{API_BASE_URL}}/v1/apps/{id}" \
-H "x-access-key: <token>"| Scope | Field | Type | Type reference | Required | Description |
|---|---|---|---|---|---|
| id#1 | id | string | __0 | Yes | OAuth app ID |
| response#2 | response | object | __0 | ||
| response#2 | response.success | boolean | __1 | Yes | |
| response#2 | response.message | string | __2 | Yes | |
| response#3 | response | object | __0 | ||
| response#3 | response.error | string | __1 | Yes |