> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create App

> Create a sandbox or production app.

Creates one sandbox or production app in your organization. You choose the environment here, and the app keeps it. See [Apps & Environments](https://docs.hopae.com/v2/guides/concepts/apps.md).

## Headers

**Authorization** `string` *required*

`Bearer sk_workspace_...`, a Workspace API key of the organization to create the app in. See [Workspace API](https://docs.hopae.com/v2/api-reference/workspace/introduction.md).

**Content-Type** `string` *required* (default: application/json)

Must be `application/json`.

**Idempotency-Key** `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](https://docs.hopae.com/v2/api-reference/workspace/introduction.md#request-behavior).

## Request Body

**name** `string` *required*

The app's display name, 1 to 200 characters.

**environment** `string` (default: production)

The kind of app to create: `sandbox` or `production`.

**mode** `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.

**workflow** `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.

**properties**

**type** `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](https://docs.hopae.com/v2/guides/reference/workflow-nodes.md#channel).

**claims** `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](https://docs.hopae.com/v2/api-reference/workspace/get-app.md).

**appId** `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.

**environment** `string` *required*

`sandbox` or `production`.

**name** `string` *required*

The app's display name.

**createdAt** `string` *required*

When the app was created, as an ISO 8601 timestamp in UTC.

The App Secret is not returned. Copy it from the [Console](https://console.hopae.com) under **Developers → API Settings**.

## Errors

Besides the authentication and subscription errors that every route can return (see [Workspace API](https://docs.hopae.com/v2/api-reference/workspace/introduction.md#authentication-and-base-url)), 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 |

```bash cURL theme={null}
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"
  }'
```

```json theme={null}
{
  "appId": "sb_7hd2kq9w",
  "environment": "sandbox",
  "name": "Integration sandbox",
  "createdAt": "2026-11-02T09:30:00.000Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.