Skip to content

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.

Request field map
FieldLocationTypeRequiredDescription
idPath parameterstringYesOAuth app ID
x-access-keyHeaderstring (<token>)YesaccessKey authorization header

Exact preserved contract; origin shown as {{API_BASE_URL}}.

Response contract
StatusContent typeResponse fields
200application/jsonsuccess: boolean (required); message: string (required)
400application/jsonerror: string (required)
404application/jsonerror: string (required)
409application/jsonerror: string (required)

Exact preserved contract.

Failure matrix
StatusMeaningAction
200App deletedRead success and message from the response body.
400Error response returnedRead error from the response body and verify the request before retrying.
404Error response returnedRead error from the response body and verify the request before retrying.
409Deletion blocked while active integrations are still connected and rely on the app for token refreshDisconnect 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.

Delete an OAuth app request example
curl -X DELETE "{{API_BASE_URL}}/v1/apps/{id}" \
  -H "x-access-key: <token>"
Interface fields
ScopeFieldTypeType referenceRequiredDescription
id#1idstring__0YesOAuth app ID
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.messagestring__2Yes
response#3responseobject__0
response#3response.errorstring__1Yes