Make an app

A web, SPA, native or machine app of the brand. A web or machine app's secret is in the response, this once; only its hash is kept. Needs `org.apps.edit`, and room under the org's plan (403 `plan_quota_exceeded`, naming the plan that has room in `required_plan`; apps that registered themselves don't count). Recorded as `app.created`.

POST/v1/orgs/{org}/brands/{brand}/apps

A web, SPA, native or machine app of the brand. A web or machine app's secret is in the response, this once; only its hash is kept. Needs org.apps.edit, and room under the org's plan (403 plan_quota_exceeded, naming the plan that has room in required_plan; apps that registered themselves don't count). Recorded as app.created.

Authorization

bearer

AuthorizationBearer <token>

An org API key (sk_live_…, sk_test_…), or an access token from the Synq issuer (the synq brand, on the accounts host) for this API.

In: header

Path Parameters

org*string

brand*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length <= 100

app_type*string

Value in

"web"
"spa"
"native"
"m2m"
"agent"

redirect_uris?array<string>

Matched exactly, port included. https; a web app or SPA may also use https on localhost, 127.0.0.1 or [::1] (a dev server on a laptop), and a native app http://localhost or http://127.0.0.1 on any port, or a scheme of its own: a reverse domain name it owns, in lowercase, such as com.example.app:/callback (RFC 8252). A native app is public and always uses PKCE.

Itemsitems <= 20

post_logout_redirect_uris?array<string>

Where the issuer may send someone after the app signs them out, matched exactly like redirect URIs

Itemsitems <= 20

backchannel_logout_uri?|

Where the issuer tells the app's server that someone signed out (OpenID Connect Back-Channel Logout): a POST with a signed logout_token. https on a public host; for apps that sign people in with a redirect

Lengthlength <= 2048

backchannel_logout_session_required?boolean

Whether the logout token and ID tokens carry sid, the session that ended. On by default

client_uri?|

Formaturi

Lengthlength <= 2048

logo_uri?|

Formaturi

Lengthlength <= 2048

policy_uri?|

Formaturi

Lengthlength <= 2048

tos_uri?|

Formaturi

Lengthlength <= 2048

initiate_login_uri?|

Where the app starts a sign-in on its own (OpenID Connect's third-party-initiated login): the brand's signed-out page links to it as "Sign in again". client_uri is its "Back to" link

Formaturi

Lengthlength <= 2048

jwks_uri?|

For private_key_jwt: where the app's keys are

Formaturi

Lengthlength <= 2048

token_endpoint_auth_method?string

How a web or machine app authenticates; client_secret_basic by default

Value in

"client_secret_basic"
"client_secret_post"
"private_key_jwt"

first_party?boolean

The brand's own app: people aren't asked to consent to it

pkce_optional?boolean

A web app may skip PKCE (not recommended); public apps never can

own_ui_sign_in?boolean

The app signs people in on its own screens, with a password, an emailed code or a passkey, through the issuer's /authorize-challenge (OAuth 2.0 for First-Party Applications), rather than sending them to the hosted page. For the brand's own web or native apps only (first_party), and off by default: the app's code then sees the passwords and codes people type. Turning first_party off turns this off too

spa_refresh_tokens?boolean

A SPA may hold refresh tokens (off by default)

sign_in_methods?array<>|

The ways to sign in this app takes, of those its brand offers: built-in (email, password, passkey, wallet) or upstream providers (github, google…). Its sign-ins offer only these, on the hosted page and its own screens (method_unavailable otherwise), sign up and add ways in with only these, and a session the brand has from another way signs in again with one of these first, on a page that says so. For an app that takes GitHub and Google alone, say, to tie each person to one of those accounts. Null, the default, takes every way the brand offers. Recorded in app.updated; not for a machine app, which signs no one in

Items1 <= items <= 13

test_sign_ins?boolean

Offer test sign-ins (test), on Synq's stages other than production only: a made-up GitHub or Google account, which your end-to-end tests describe (its age, its public repositories, a Workspace domain…), on the hosted page or headless through /authorize-challenge. Every account it makes says test: true in linked_accounts, its subject starts test-, and its address is never verified. Off by default; never for a machine app. Production refuses it (validation_failed)

refresh_token_reuse_window_seconds?integer

Seconds after a refresh token is rotated during which the same refresh token, presented again by this app, gets back the very tokens its rotation gave (the same refresh, access and ID tokens) instead of ending its grant. For an app on several servers or processes (Vercel, replicas) whose requests may refresh at once. 0, the default, is no window: a rotated refresh token presented again ends its grant. Nothing comes back after the person's sessions are ended or the grant is revoked, and a replay must ask for the scope and resource the rotation did. Each replay is counted and recorded as app.refresh_token_replayed, since inside the window a reused token isn't caught as stolen. 0 to 60, for web apps only: a replay still needs the app's secret. A public app (SPA, native, agent) has no secret, so a thief replaying a stolen refresh token inside the window would get the new tokens, and it can't have one; nor can a machine app, which gets no refresh tokens

Range0 <= value <= 60

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/v1/orgs/string/brands/string/apps" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "app_type": "web"  }'

{  "id": "string",  "brand_id": "string",  "name": "string",  "app_type": "web",  "source": "dashboard",  "first_party": true,  "own_ui_sign_in": true,  "sign_in_methods": [    "string"  ],  "test_sign_ins": true,  "disabled": true,  "redirect_uris": [    "string"  ],  "post_logout_redirect_uris": [    "string"  ],  "backchannel_logout_uri": "string",  "backchannel_logout_session_required": true,  "client_uri": "string",  "logo_uri": "string",  "policy_uri": "string",  "tos_uri": "string",  "initiate_login_uri": "string",  "jwks_uri": "string",  "token_endpoint_auth_method": "string",  "pkce_optional": true,  "spa_refresh_tokens": true,  "refresh_token_reuse_window_seconds": 0,  "previous_secret_expires_at": "2019-08-24T14:15:22Z",  "last_used_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "warnings": [    {      "code": "string",      "message": "string"    }  ],  "client_secret": "string"}

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`