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.
| Field | Required | Type | Constraints / notes |
|---|---|---|---|
| name | Optional | string | 1 <= length <= 200 |
| imageUrl | Optional | string | null | Accepts a string or null |
| clientSecret | Optional | string | 1 <= length; rotates the stored client secret; clientId stays the same |
Exact source contract; all body fields optional.
| Field | Required | Type | Constraints / notes |
|---|---|---|---|
| success | Required | boolean | Top-level success flag |
| app | Required | object | Updated OAuth app object |
| app.id | Required | string | OAuth app ID |
| app.platform | Required | string | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" |
| app.name | Required | string | Updated app name |
| app.imageUrl | Required | string | null | Updated image URL or null |
| app.clientId | Required | string | Immutable; unchanged by this operation |
| app.integrationCount | Required | integer | 0 <= value; number of active integrations connected under this app |
| app.createdAt | Required | string | date-time |
| app.updatedAt | Required | string | date-time |
Exact source contract for the 200 app object; client secret is never returned.
| Status | Response shape | What 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.
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>"
}'{
"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"
}
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| id#1 | id | string | __0 | Yes | OAuth app ID | |
| body#2 | body | object | __0 | Yes | ||
| body#2 | body.name | string | __1 | No | kind: schemaLength; value: 1 <= length <= 200 | |
| body#2 | body.imageUrl | string | null | __2 | No | ||
| body#2 | body.imageUrl[variant1] | string | __2_type:string | |||
| body#2 | body.imageUrl[variant2] | null | __2_type:null | |||
| body#2 | body.clientSecret | string | __3 | No | Rotate 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#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.app | object | __2 | Yes | ||
| response#3 | response.app.id | string | __3 | Yes | Pass this as appId when connecting | |
| response#3 | response.app.platform | string | __4 | Yes | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| response#3 | response.app.name | string | __5 | Yes | ||
| response#3 | response.app.imageUrl | string | null | __6 | Yes | ||
| response#3 | response.app.imageUrl[variant1] | string | __6_type:string | |||
| response#3 | response.app.imageUrl[variant2] | null | __6_type:null | |||
| response#3 | response.app.clientId | string | __7 | Yes | The OAuth app client id. The client secret is never returned. | |
| response#3 | response.app.integrationCount | integer | __8 | Yes | Number of active integrations connected under this app | kind: schemaRange; value: 0 <= value |
| response#3 | response.app.createdAt | string | __9 | Yes | kind: schemaFormat; value: date-time | |
| response#3 | response.app.updatedAt | string | __10 | Yes | kind: schemaFormat; value: date-time | |
| response#4 | response | object | __0 | |||
| response#4 | response.error | string | __1 | Yes |