curl --request POST \
--url 'https://api.hopae.com/connect/v2/apps' \
--header 'Authorization: Bearer sk_workspace_...' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 4f7c2a9e-1b3d-4e8a-9c6f-0d2b5a7e3c11' \
--data '{
"name": "Integration sandbox",
"environment": "sandbox",
"mode": "quickstart"
}'
{
"appId": "sb_7hd2kq9w",
"environment": "sandbox",
"name": "Integration sandbox",
"createdAt": "2026-11-02T09:30:00.000Z"
}
Apps
Create App
Create a sandbox or production app.
POST
/
connect
/
v2
/
apps
curl --request POST \
--url 'https://api.hopae.com/connect/v2/apps' \
--header 'Authorization: Bearer sk_workspace_...' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 4f7c2a9e-1b3d-4e8a-9c6f-0d2b5a7e3c11' \
--data '{
"name": "Integration sandbox",
"environment": "sandbox",
"mode": "quickstart"
}'
{
"appId": "sb_7hd2kq9w",
"environment": "sandbox",
"name": "Integration sandbox",
"createdAt": "2026-11-02T09:30:00.000Z"
}
Creates one sandbox or production app in your organization. You choose the environment here, and the app keeps it. See Apps & Environments.
The App Secret is not returned. Copy it from the Console under Developers → API Settings.
Headers
string
required
Bearer sk_workspace_..., a Workspace API key of the organization to create the app in. See Workspace API.string
default:"application/json"
required
Must be
application/json.string
A unique key for this request, up to 255 characters. If you retry with the same key and the same body within 24 hours, you get the stored response with
Idempotency-Replayed: true, and no second app is created. See Request behavior.Request Body
string
required
The app’s display name, 1 to 200 characters.
string
default:"production"
The kind of app to create:
sandbox or production.string
default:"blank"
Sandbox apps only. Sending
mode for a production app returns 400.blank: the app starts with no connections and no workflow.quickstart: the app starts with every connection that supports sandbox already activated, sample company details, and a default managed workflow that enables one connection per display group.
object
Production apps only. Creates the app’s default workflow. Without it, a production app starts with no workflow. Sending
workflow for a sandbox app returns 400.The workflow has Automatically enable newly activated connections turned on, so each connection you activate later is enabled in it. It does not activate any connection.Show properties
Show properties
string
required
managed or api. Records whether you plan to run the workflow through the hosted flow or the REST API. It does not change how the workflow runs. See Workflow Nodes.string[]
required
The claims the workflow requests. Each value must be one of
name, given_name, family_name, middle_name, nickname, preferred_username, picture, gender, birthdate, nationality, phone_number, phone_number_verified, email, email_verified, zoneinfo, locale, address, profile, or source_id. Send [] to request no claims yet.workflow accepts only type and claims. Any other key returns 400.Response
201 Created. The Location header holds the new app’s path, /connect/v2/apps/{appId}, which you can read with Get App.
string
required
The app ID. It is also the app’s OIDC
client_id and its Basic-auth username on the verification API. Read environment to tell sandbox and production apps apart; do not infer it from the ID.string
required
sandbox or production.string
required
The app’s display name.
string
required
When the app was created, as an ISO 8601 timestamp in UTC.
Errors
Besides the authentication and subscription errors that every route can return (see Workspace API), this endpoint returns:| HTTP | Code | When |
|---|---|---|
| 400 | VALIDATION_INVALID_PARAMETER | name is missing, empty, or longer than 200 characters. environment, mode, or workflow.type has an unknown value. mode is sent for a production app, or workflow for a sandbox app. workflow has an unknown key, or workflow.claims has a claim outside the list. Idempotency-Key is longer than 255 characters |
| 409 | IDEMPOTENCY_KEY_CONFLICT | The Idempotency-Key was used before with a different body |
| 409 | IDEMPOTENCY_REQUEST_IN_PROGRESS | An earlier request with the same Idempotency-Key is still running |
curl --request POST \
--url 'https://api.hopae.com/connect/v2/apps' \
--header 'Authorization: Bearer sk_workspace_...' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 4f7c2a9e-1b3d-4e8a-9c6f-0d2b5a7e3c11' \
--data '{
"name": "Integration sandbox",
"environment": "sandbox",
"mode": "quickstart"
}'
{
"appId": "sb_7hd2kq9w",
"environment": "sandbox",
"name": "Integration sandbox",
"createdAt": "2026-11-02T09:30:00.000Z"
}