<Intro>

<EndpointHeader />

<Description>

Provisions a new Realtime app for the workspace and returns it together with the initial key. The key secret is included in this response only and is never returned again — store it now; if lost, create a new key and revoke this one.

</Description>

</Intro>

<Payload kind="request">

<Field name="client_events" type="boolean" />

<Field name="connection_counting" type="boolean" />

<Field name="authorized_connections" type="boolean" />

<Field name="name" type="string" required />

<Field name="region" type="object" required>

<Description>

The region this app runs in. Unlike other Bird products, a Realtime app can be placed in a region other than the workspace's home region. Immutable after creation.

</Description>

</Field>

</Payload>

<Payload kind="response">

<Field name="created_at" type="string" required />

<Field name="updated_at" type="string" required />

<Field name="client_events" type="boolean" required>

<Description>

Allow clients to trigger events directly (client events).

</Description>

</Field>

<Field name="connection_counting" type="boolean" required>

<Description>

Emit connection-count events on channels.

</Description>

</Field>

<Field name="authorized_connections" type="boolean" required>

<Description>

Require every connection to be authorized.

</Description>

</Field>

<Field name="id" type="string" required />

<Field name="app_id" type="integer" required>

<Description>

The numeric Realtime app id. Use it together with a key and secret to initialize a Realtime client/server SDK. Immutable.

</Description>

</Field>

<Field name="name" type="string" required />

<Field name="region" type="object" required>

<Description>

The region this app runs in. Unlike other Bird products, a Realtime app can be placed in a region other than the workspace's home region. Immutable after creation.

</Description>

</Field>

<Field name="status" type="string" required>

<Description>

Lifecycle state of the app. `active` apps serve connections; `suspended` apps are provisioned but reject connections.

</Description>

<Description>

Possible values: `active`, `suspended`

</Description>

</Field>

<Field name="key" type="object" required>

<Description>

The app's initial key, including its one-time secret. Present in this create response only; the secret is never returned again.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="key." required />

<Field name="key" type="string" prefix="key." required>

<Description>

The public app key clients use to connect.

</Description>

</Field>

<Field name="secret" type="string" prefix="key.">

<Description>

The key secret, used for server-side request signing. Returned only when the key is created, and never shown again — store it securely. If lost, create a new key and revoke this one.

</Description>

</Field>

<Field name="revoked_at" type="nullable string" prefix="key." required>

<Description>

When the key was revoked, or null if still active.

</Description>

</Field>

<Field name="created_at" type="string" prefix="key." required />

</FieldChildren>

</Field>

</Payload>