Create App API: Register Your Own OAuth App (Bring Your Own Keys)
The Create App API registers your own OAuth app credentials for a supported social platform under Bring Your Own Keys. You store the client credentials of your own OAuth app for a platform, then supply the identifier from the response under the appId name in calls to /v1/connect/:platform for linking accounts beneath the registered app. The operation is POST /v1/apps/ and requires the x-access-key header.
Register your own OAuth app (Bring Your Own Keys)
Use this endpoint when you want accounts connected under your own OAuth app rather than a shared app. The workflow has two steps: first register the app credentials with POST /v1/apps/, then supply the identifier from the response under the appId name in calls to /v1/connect/:platform for linking accounts beneath the registered app. Keep that identifier with the rest of your project configuration, because it links the registered credentials to later account connections. The request example titled Create App API request example shows the exact payload shape, and the field map titled Create App API request fields lists every field with its requiredness and constraints.
Authorization
Every request must include the accessKey in the x-access-key header, with the value set to your token. Send the request body as application/json. The captured contract specifies this header requirement; it does not specify an authentication failure status or behavior, so no such status is described here. The worked request example includes the x-access-key header alongside the Content-Type header so you can copy the complete header set.
Request Body
The request body is an application/json object with four required fields and one optional field. platform is required and must be one of the ten enum values listed in the field map. name is required, is a label for the app such as Acme Twitter OAuth App, and must be between 1 and 200 characters long. clientId is required and is the client id of your OAuth app for the chosen platform, with a minimum length of 1. clientSecret is required, is the client secret of your OAuth app, and must be at least 1 character long. imageUrl is optional, is an icon URL for the app, and must be formatted as a URI when supplied. Before sending, check each field against the field map titled Create App API request fields: an empty name, an unsupported platform value, or a malformed imageUrl are the most common self-inflicted failures.
Response Body
A successful call returns 201 with an application/json body containing success set to true and an app object. The app object contains id, platform, name, imageUrl, clientId, integrationCount, createdAt, and updatedAt. The id is the value you supply under the appId name when linking accounts beneath this app. imageUrl is returned as a string or null, so handle the null case when the optional field was omitted. integrationCount reports the number of active integrations connected under this app and starts at 0 in the example. createdAt and updatedAt are date-time strings. The response example titled Create App API 201 response example shows the full success shape.
201 application/json
The 201 response confirms the app was registered and returns the app object described above. Note what is absent: clientSecret is never returned in the response, so you cannot recover it from this call. If you need to reference the app later, store the identifier from the response and the clientId you already have. The clientSecret you submitted is Stored encrypted, so treat your own copy of the secret as the only place it exists in plain text. The failure matrix titled Create App API response and failure matrix maps each status code to its response shape.
400 application/json
A 400 response returns an application/json body with the shape {"error": "string"}. The captured contract does not specify which conditions trigger a 400 or what values the error string can take, so do not build logic that assumes a particular message. When you receive a 400, re-check the request body against the field map: confirm platform is one of the ten enum values, name is 1 to 200 characters, clientId and clientSecret are non-empty, and imageUrl is a valid URI if present. The error example titled Create App API 400 and 409 error response example shows the exact shape.
409 application/json
A 409 response also returns an application/json body with the shape {"error": "string"}. As with 400, the captured contract does not specify the exact conditions that trigger a 409, duplicate-app semantics, or the possible error-message values, so do not assume a cause or invent a deduplication rule. When you receive a 409, read the returned error string and inspect already-registered apps for your project before retrying. The error example titled Create App API 400 and 409 error response example shows the exact shape.
Worked example and next step: pass the returned id as appId to /v1/connect/:platform
After a 201 response, take the identifier from the response and supply it under the appId name in calls to /v1/connect/:platform for linking accounts beneath the registered app. Verify the connection step separately: a successful app registration does not by itself connect any account, and integrationCount on the app reflects active integrations connected under it. For client-secret handling, remember that clientSecret is Stored encrypted on input and is never returned in the 201 response, so keep your own secure copy and never log the secret in request traces. If a later call fails, first confirm you are using the exact identifier returned by this endpoint rather than the clientId, which serves a different purpose.
| Field | Required | Type | Constraints | Description |
|---|---|---|---|---|
| platform | Required | string | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | The platform the OAuth app belongs to |
| name | Required | string | 1 <= length <= 200 | A label for this app (e.g. "Acme Twitter OAuth App") |
| clientId | Required | string | 1 <= length | The client id of your OAuth app for this platform |
| clientSecret | Required | string | 1 <= length | The client secret of your OAuth app. Stored encrypted. |
| imageUrl | Optional | string | Format: uri | Optional icon URL for the app |
Exact captured request contract for POST /v1/apps/.
| Status | Response shape | What it means | Failure check |
|---|---|---|---|
| 201 | {"success": true, "app": {...}} | App registered; app object returned with id, platform, name, imageUrl, clientId, integrationCount, createdAt, updatedAt | Store the returned id for use as appId; clientSecret is never returned |
| 400 | {"error": "string"} | Request rejected; exact trigger conditions not supplied | Re-check platform enum, name length 1-200, non-empty clientId and clientSecret, and imageUrl URI format |
| 409 | {"error": "string"} | Request conflicts with existing state; exact trigger conditions and duplicate semantics not supplied | Read the returned error string and inspect already-registered apps before retrying |
Trigger conditions beyond the status codes are not supplied in the captured contract; do not assume specific causes or error-message values.
Frequently asked questions
What is required to register an app with the Create App API?
Send POST /v1/apps/ with the x-access-key header set to your token, Content-Type application/json, and a body containing platform, name, clientId, and clientSecret. imageUrl is optional and must be a URI when supplied.
What does a successful Create App API response return?
The 201 response returns the app object including its id, platform, name, imageUrl, clientId, integrationCount, createdAt, and updatedAt. It does not return clientSecret.
How do I use the returned app id?
Supply that identifier under the appId name in calls to /v1/connect/:platform for linking accounts beneath the registered app.
What do the 400 and 409 responses look like?
Both use the shape {"error": "string"}. The captured contract does not specify the exact trigger conditions or error-message values for either status, so check the returned error string rather than assuming a cause.
curl -X POST "{{API_BASE_URL}}/v1/apps/" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"platform": "twitter",
"name": "string",
"clientId": "string",
"clientSecret": "string"
}'{
"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 |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.platform | string | __1 | Yes | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| body#1 | body.name | string | __2 | Yes | A label for this app (e.g. "Acme Twitter OAuth App") | kind: ; value: 1 <= length <= 200 |
| body#1 | body.clientId | string | __3 | Yes | The client id of your OAuth app for this platform | kind: ; value: 1 <= length |
| body#1 | body.clientSecret | string | __4 | Yes | The client secret of your OAuth app. Stored encrypted. | kind: ; value: 1 <= length |
| body#1 | body.imageUrl | string | __5 | No | Optional icon URL for the app | kind: ; value: uri |
| 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: schemaValueIn; 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: schemaRange; value: 0 <= value |
| response#2 | response.app.createdAt | string | __9 | Yes | kind: schemaFormat; value: date-time | |
| response#2 | response.app.updatedAt | string | __10 | Yes | kind: schemaFormat; value: date-time | |
| response#3 | response | object | __0 | |||
| response#3 | response.error | string | __1 | Yes |