Get OAuth App API: Get a single OAuth app
The Get OAuth App API lets you get a single OAuth app by its OAuth app ID. Use GET /v1/apps/{id} when you need to inspect one registered BYOK OAuth app for a project, including its platform, clientId, integrationCount, imageUrl, createdAt, and updatedAt values, before you decide whether to use, update, or replace that app.
Get a single OAuth app — GET {{API_BASE_URL}}/v1/apps/{id}
Get a single OAuth app is the operation for retrieving one BYOK OAuth app record by ID. The request uses GET with the exact path /v1/apps/{id}, where the id segment is replaced with the OAuth app ID you want to inspect. This is a read operation: it returns the stored app details for that ID and does not create, update, or delete the app. If you do not yet know the ID, start from the related list operation for registered OAuth apps for the project, then use the returned ID here. If you need to change the record after inspecting it, use the related update operation rather than repeating this lookup.
Authorization
Authorization uses the accessKey credential sent in the x-access-key header. Place the token value in that header on the GET request, as shown in the Get a single OAuth app request example. The captured contract identifies the header name as x-access-key and the credential name as accessKey; it does not specify additional authorization schemes for this endpoint. Keep the token out of the path and out of the response handling code, and treat a missing or invalid credential as a request problem to check before debugging the app ID itself.
Path Parameters
The path contains one required parameter. The id parameter is a required string described as the OAuth app ID. Supply the exact ID value in place of {id} in /v1/apps/{id}; there are no optional path parameters and no query parameters in the captured contract for this operation. A practical check is to compare the ID in your request URL with the id field returned inside the app object on a successful response, and to confirm that the platform, clientId, and integrationCount values belong to the app you intended to inspect.
Response Body — 200 application/json
A successful lookup returns 200 with an application/json body containing a required success boolean and a required app object. The app object always carries the same field set in the captured contract: id, platform, name, imageUrl, clientId, integrationCount, createdAt, and updatedAt. Use the field map in the Response field map table to distinguish string fields from the nullable imageUrl, the integer integrationCount, and the date-time timestamp fields. The clientId field returns the OAuth app client id, while the client secret is never returned, so do not design client code that expects a secret field in this response. The integrationCount field reports the number of active integrations connected under this app, and the id field is the value to pass as appId when connecting. See the Get a single OAuth app 200 response example for the complete success shape.
Error Responses — 400 and 404 application/json
Error responses use the same application/json error shape for both captured failure statuses. A 400 response returns a required error string, and a 404 response also returns a required error string, as shown in the Get a single OAuth app error response example. The failure matrix in the Failure matrix table separates the two statuses so client code can branch on the status code first and then read the error message. Because the captured contract does not define the exact conditions or message values for each status, handle 400 as a malformed or unacceptable request case and 404 as a case where the requested app was not found, without assuming more specific causes than the status and error field provide.
Worked Example
To run the lookup, replace {id} with the OAuth app ID, set the x-access-key header to your token, and send the GET request shown in the Get a single OAuth app request example. On a 200 response, read app.id to confirm the lookup, app.platform to confirm the platform enum value, app.clientId to confirm the public client identifier, app.integrationCount to see how many active integrations are connected under the app, and app.createdAt and app.updatedAt to review when the record was created and last updated. Treat app.imageUrl as string or null, so guard any UI or logging code that displays it. On a 400 or 404 response, read the error string and branch on the status code using the Failure matrix table. If the ID came from a list response, re-check that the ID was copied without extra whitespace or URL encoding changes before retrying.
| Field | Type | Required | Notes |
|---|---|---|---|
| id | string | Yes | OAuth app ID; supplied in the path as /v1/apps/{id}. |
Captured contract; no additional parameters specified.
| Field | Type | Required | Notes |
|---|---|---|---|
| success | boolean | Yes | Top-level success flag. |
| app | object | Yes | The single OAuth app object. |
| app.id | string | Yes | Pass this as appId when connecting. |
| app.platform | string | Yes | Enum: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness". |
| app.name | string | Yes | App name. |
| app.imageUrl | string | null | Yes | Image URL or null. |
| app.clientId | string | Yes | The OAuth app client id. The client secret is never returned. |
| app.integrationCount | integer | Yes | Number of active integrations connected under this app; 0 <= value. |
| app.createdAt | string | Yes | Date-time timestamp. |
| app.updatedAt | string | Yes | Date-time timestamp. |
Captured contract for the 200 application/json response.
| Status | Content type | Body field | Handling |
|---|---|---|---|
| 200 | application/json | success (boolean, required); app (object, required) | Read the app object, including id, platform, clientId, integrationCount, imageUrl, createdAt, and updatedAt. |
| 400 | application/json | error (string, required) | Branch on 400 first, then read the error string; do not assume a more specific cause than the captured contract provides. |
| 404 | application/json | error (string, required) | Branch on 404 first, then read the error string; verify the OAuth app ID before retrying. |
Captured contract provides status codes and the error field only; exact error conditions and message values are not specified.
curl -X GET "{{API_BASE_URL}}/v1/apps/{id}" \
-H "x-access-key: <token>"{
"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 | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.app | object | __2 | Yes | ||
| response#2 | response.app.id | string | __3 | Yes | Pass this as appId when connecting | |
| response#2 | response.app.platform | string | __4 | Yes | kind: ; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| response#2 | response.app.name | string | __5 | Yes | ||
| response#2 | response.app.imageUrl | string | null | __6 | Yes | ||
| response#2 | response.app.imageUrl[variant1] | string | __6_type:string | |||
| response#2 | response.app.imageUrl[variant2] | null | __6_type:null | |||
| response#2 | response.app.clientId | string | __7 | Yes | The OAuth app client id. The client secret is never returned. | |
| response#2 | response.app.integrationCount | integer | __8 | Yes | Number of active integrations connected under this app | kind: ; value: 0 <= value |
| response#2 | response.app.createdAt | string | __9 | Yes | kind: ; value: date-time | |
| response#2 | response.app.updatedAt | string | __10 | Yes | kind: ; value: date-time | |
| response#3 | response | object | __0 | |||
| response#3 | response.error | string | __1 | Yes |