Skip to content

Update OAuth App API

Use the Update OAuth App API to change an existing OAuth app in place with PATCH /v1/apps/{id}. You can update the display name, replace or clear the image, or rotate the stored secret without changing the identity that existing integrations were connected under. This page covers the exact request fields, the fields that cannot change, and how to interpret the 200, 400, and 404 responses.

Update an OAuth app: PATCH {{API_BASE_URL}}/v1/apps/{id}

Update an OAuth app when only its presentation or stored secret needs to change. This operation can adjust the name, swap the image, or replace the stored secret. Two identity fields stay fixed throughout: clientId and platform. Existing refresh tokens were issued under a particular clientId, so pointing an integration at a different app identity would break that connection. When a different clientId or platform is required, the path is to create a new OAuth app and reconnect, rather than attempting an in-place edit of those fields.

Authorization with x-access-key

Send the request with the x-access-key header containing your token. The header name is x-access-key and the value is the token itself. Include Content-Type: application/json when sending a JSON request body. Check that the header name is spelled exactly as shown and that the token value is present before troubleshooting other parts of the request.

Path parameter id

The path contains one required parameter, id, which is the OAuth app ID. Replace {id} in /v1/apps/{id} with that identifier. There are no other path parameters in this contract. Use the exact ID returned for the app you intend to update, and verify it against the app you expect to change.

Request body field map: name, imageUrl, clientSecret

All request body fields are optional, so send only the fields you want to change. The name field is a string between 1 and 200 characters long. The imageUrl field accepts a string or null. The clientSecret field is a string of at least 1 character and replaces the stored secret. After a secret replacement, clientId remains unchanged, so integrations already connected under it continue to reference the same identifier. Moving to a different app identity instead requires creating a new OAuth app and reconnecting. See the request field map below for the full input contract, and see the request example for a complete origin-modular call.

Immutable fields and the create-and-reconnect alternative

Update in place when the app identity is correct and only the name, image, or secret needs to change. Replacing clientSecret is appropriate when the stored secret should be refreshed while integrations keep using the same clientId. Create a new OAuth app and reconnect when the clientId itself must change or when the platform must change, because neither clientId nor platform can be updated through this operation. Do not send clientId or platform in the request body; they are not part of the update contract.

200 response app object field map

A successful update returns 200 with a JSON body containing success set to true and an app object. The app object includes id, platform, name, imageUrl, clientId, integrationCount, createdAt, and updatedAt. The platform value is one of twitter, instagram, youtube, tiktok, pinterest, linkedin, bluesky, facebook, threads, or googlebusiness. The client secret is never returned in the response, so do not expect clientSecret in the app object and do not store the response as a copy of the secret. See the response field map below for types and constraints, and see the 200 response example for the exact shape.

400 and 404 error shapes and failure matrix

A 400 response returns a JSON body with an error string. A 404 response returns the same JSON shape with an error string. The supplied contract does not define specific error codes or messages for either status, so handle both by reading the error value and checking the request against the field constraints and the path ID. For a 400, re-check the body fields, especially the name length and the clientSecret length. For a 404, re-check that the id in the path is the correct OAuth app ID. See the failure matrix below and the error response example for the exact shape.

Origin-modular request example

Build the request by combining the origin placeholder {{API_BASE_URL}} with the unchanged path /v1/apps/{id}, using the PATCH method, the x-access-key header, and a JSON body containing only the fields you want to change. After the call, verify the 200 response: confirm success is true, confirm clientId and platform are unchanged, confirm the fields you sent reflect the new values, and confirm integrationCount still reflects the integrations connected under the app. If you rotated clientSecret, keep the value you sent in your own records, because the response will not return it.

Request body field map
FieldRequiredTypeConstraints / notes
nameOptionalstring1 <= length <= 200
imageUrlOptionalstring | nullAccepts a string or null
clientSecretOptionalstring1 <= length; rotates the stored client secret; clientId stays the same

Exact source contract; all body fields optional.

200 response app object field map
FieldRequiredTypeConstraints / notes
successRequiredbooleanTop-level success flag
appRequiredobjectUpdated OAuth app object
app.idRequiredstringOAuth app ID
app.platformRequiredstring"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
app.nameRequiredstringUpdated app name
app.imageUrlRequiredstring | nullUpdated image URL or null
app.clientIdRequiredstringImmutable; unchanged by this operation
app.integrationCountRequiredinteger0 <= value; number of active integrations connected under this app
app.createdAtRequiredstringdate-time
app.updatedAtRequiredstringdate-time

Exact source contract for the 200 app object; client secret is never returned.

Failure matrix for 200, 400, and 404
StatusResponse shapeWhat to check
200{"success": true, "app": {...}}Confirm success, unchanged clientId and platform, and updated fields
400{"error": "string"}Re-check body fields against type, nullability, and length constraints
404{"error": "string"}Re-check that the id path parameter is the correct OAuth app ID

Only the supplied {"error": "string"} shape is defined; no specific error codes or messages are supplied.

Update an OAuth app request example
curl -X PATCH "{{API_BASE_URL}}/v1/apps/{id}" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "name": "Updated app name",
    "imageUrl": "https://example.com/app-icon.png",
    "clientSecret": "<new-client-secret>"
  }'
200 response example
{
  "success": true,
  "app": {
    "id": "string",
    "platform": "twitter",
    "name": "string",
    "imageUrl": "string",
    "clientId": "string",
    "integrationCount": 0,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
400 and 404 error response example
{
  "error": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
id#1idstring__0YesOAuth app ID
body#2bodyobject__0Yes
body#2body.namestring__1Nokind: schemaLength; value: 1 <= length <= 200
body#2body.imageUrlstring | null__2No
body#2body.imageUrl[variant1]string__2_type:string
body#2body.imageUrl[variant2]null__2_type:null
body#2body.clientSecretstring__3NoRotate the stored client secret. The clientId stays the same so existing tokens keep working — to switch to a different app, create a new OAuth app and reconnect.kind: ; value: 1 <= length
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.appobject__2Yes
response#3response.app.idstring__3YesPass this as appId when connecting
response#3response.app.platformstring__4Yeskind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#3response.app.namestring__5Yes
response#3response.app.imageUrlstring | null__6Yes
response#3response.app.imageUrl[variant1]string__6_type:string
response#3response.app.imageUrl[variant2]null__6_type:null
response#3response.app.clientIdstring__7YesThe OAuth app client id. The client secret is never returned.
response#3response.app.integrationCountinteger__8YesNumber of active integrations connected under this appkind: schemaRange; value: 0 <= value
response#3response.app.createdAtstring__9Yeskind: schemaFormat; value: date-time
response#3response.app.updatedAtstring__10Yeskind: schemaFormat; value: date-time
response#4responseobject__0
response#4response.errorstring__1Yes