Skip to content

List OAuth apps API

The List OAuth apps API returns the OAuth apps registered for a project. Use it to discover which apps are available before connecting an account, to filter OAuth apps by platform, to search OAuth apps by name, and to paginate a larger set of results. Each returned app includes its identifier, platform, name, imageUrl, clientId, integrationCount, createdAt, and updatedAt values, so a client can present the right app and use its id as appId when connecting.

Operation summary: GET /v1/apps/

The operation is GET /v1/apps/. It lists registered OAuth apps for the project identified by the request credentials. Call it without query parameters to retrieve the first page using the defaults, or add the optional query parameters described below to narrow or paginate the result set. The successful response uses status 200 with an application/json body containing success, total, page, limit, and apps. The apps array contains one object per matching OAuth app, and total reports the overall count for the query while page and limit echo the pagination window used for the response.

Authorization

Send the access key in the x-access-key header on every request. The header value is the token placeholder shown in the request example titled List OAuth apps request. Keep the token out of query strings and out of logs, and treat a missing or invalid header as a client-side failure to check before debugging filters or pagination. No other authorization header is specified for this operation.

Query parameters field map

All four query parameters are optional. Use platform to restrict results to one platform value from the stated enum, page to choose the result page, limit to choose how many apps to return per page, and name to match a case-insensitive substring of the app name. When you combine filters, the response total reflects the combined query, so verify total, page, and limit together rather than assuming the length of the apps array is the full result count. The field map titled Query parameters field map lists the type, requiredness, default, range, enum, and length constraint for each parameter, and the validation matrix titled Validation and pagination checks lists the checks derived only from those stated constraints.

Response body field map

In the 200 response, success is a required boolean, total is a required integer with a minimum of 0, page is a required integer with a minimum of 1, limit is a required integer with a minimum of 1, and apps is a required array of app objects. Each app object requires id as a string, platform as a string from the same platform enum, name as a string, imageUrl as string or null, clientId as a string, integrationCount as an integer with a minimum of 0, and createdAt and updatedAt as date-time strings. Use id as appId when connecting, use clientId to identify the OAuth app client, and use integrationCount to see how many active integrations are connected under that app. The client secret is never returned in this response. The field map titled Response body field map gives the complete type and requiredness detail, and the example titled 200 application/json response example shows the exact success shape.

Request and response workflow

Build the request with the origin placeholder followed by the unchanged path /v1/apps/, add the x-access-key header, and append query parameters only when filtering or paginating. After a 200 response, read success first, then use total to decide whether more pages exist, and iterate by increasing page while keeping limit within its stated range. For each app, preserve imageUrl as nullable, format createdAt and updatedAt as date-time values, and do not expect a client secret field. If the apps array is empty, treat that as a valid empty result for the current filters and adjust platform or name before assuming no apps are registered.

Validation and pagination notes

Validate inputs against the stated constraints before sending: platform must be one of the listed enum values, page must be at least 1, limit must be between 1 and 100, and name must be between 1 and 200 characters when supplied. Check that the response contains the required top-level fields and that every app object contains its required fields with the stated types, including a nullable imageUrl and date-time createdAt and updatedAt. Because no error-response contract beyond the 200 response is specified here, do not invent error bodies or retry rules; instead, surface unexpected statuses to the caller and re-check the header, path, and parameter constraints first.

Query parameters field map
ParameterRequiredTypeDefault / constraintUse
platformOptionalstring"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"Filter OAuth apps by platform
pageOptionalintegerDefault 1; 1 <= valueSelect the result page
limitOptionalintegerDefault 50; 1 <= value <= 100Set page size
nameOptionalstring1 <= length <= 200; case-insensitive substring match on app nameSearch OAuth apps by name

All parameters are optional per the source contract.

Response body field map
FieldRequiredTypeConstraint / note
successRequiredbooleanTop-level result flag
totalRequiredinteger0 <= value
pageRequiredinteger1 <= value
limitRequiredinteger1 <= value
appsRequiredarray<object>Array of app objects
apps[].idRequiredstringPass this as appId when connecting
apps[].platformRequiredstring"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
apps[].nameRequiredstringApp name
apps[].imageUrlRequiredstring | nullNullable image URL
apps[].clientIdRequiredstringOAuth app client id; client secret is never returned
apps[].integrationCountRequiredinteger0 <= value; number of active integrations connected under this app
apps[].createdAtRequiredstringdate-time format
apps[].updatedAtRequiredstringdate-time format

Response status is 200 with application/json.

Validation and pagination checks
CheckStated constraintClient action
Authorization header presentx-access-key header with <token>Send the header on every request
platform valueMust be one of the listed enum valuesOmit platform or use an exact enum value
page value1 <= value; default 1Use an integer of at least 1
limit value1 <= value <= 100; default 50Use an integer within the range
name value1 <= length <= 200Omit name or keep it within the length range
Pagination completenesstotal, page, and limit are required in the responseCompare total with page and limit before stopping
App object completenessAll nested app fields are required; imageUrl is string | nullHandle null imageUrl and date-time createdAt/updatedAt

Derived only from stated constraints; no error contract invented.

List OAuth apps request
curl -X GET "{{API_BASE_URL}}/v1/apps/" \
  -H "x-access-key: <token>"
List OAuth apps with platform, pagination, and name filters
curl -X GET "{{API_BASE_URL}}/v1/apps/?platform=twitter&page=1&limit=50&name=example" \
  -H "x-access-key: <token>"
200 application/json response example
{
  "success": true,
  "total": 0,
  "page": 1,
  "limit": 1,
  "apps": [
    {
      "id": "string",
      "platform": "twitter",
      "name": "string",
      "imageUrl": "string",
      "clientId": "string",
      "integrationCount": 0,
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
platform#1platformstring__0Nokind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
page#2pageinteger__0Nokind: schemaDefault; value: 1 | kind: schemaRange; value: 1 <= value
limit#3limitinteger__0Nokind: schemaDefault; value: 50 | kind: schemaRange; value: 1 <= value <= 100
name#4namestring__0NoCase-insensitive substring match on app namekind: schemaLength; value: 1 <= length <= 200
response#5responseobject__0
response#5response.successboolean__1Yes
response#5response.totalinteger__2Yeskind: schemaRange; value: 0 <= value
response#5response.pageinteger__3Yeskind: schemaRange; value: 1 <= value
response#5response.limitinteger__4Yeskind: schemaRange; value: 1 <= value
response#5response.appsarray<object>__5Yes
response#5response.apps[]object__6
response#5response.apps[].idstring__7YesPass this as appId when connecting
response#5response.apps[].platformstring__8Yeskind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#5response.apps[].namestring__9Yes
response#5response.apps[].imageUrlstring | null__10Yes
response#5response.apps[].imageUrl[variant1]string__10_type:string
response#5response.apps[].imageUrl[variant2]null__10_type:null
response#5response.apps[].clientIdstring__11YesThe OAuth app client id. The client secret is never returned.
response#5response.apps[].integrationCountinteger__12YesNumber of active integrations connected under this appkind: schemaRange; value: 0 <= value
response#5response.apps[].createdAtstring__13Yeskind: schemaFormat; value: date-time
response#5response.apps[].updatedAtstring__14Yeskind: schemaFormat; value: date-time