Skip to content
Exhale

Create the first account

POST
/api/v1/auth/setup
curl --request POST \
  --url http://127.0.0.1:8484/api/v1/auth/setup \
  --header 'Content-Type: application/json' \
  --data '{ "code": "example", "currency": "example", "email": "example", "householdName": "example", "locale": "example", "name": "example", "password": "example", "timezone": "example" }'

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
$schema

A URL to the JSON Schema for this object.

string format: uri
code

Setup code printed in the server log; not needed from the server’s own machine

string
currency
string
email
required
string
householdName
string
locale
string
name
required
string
password
required
string
timezone
string

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
$schema

A URL to the JSON Schema for this object.

string format: uri
assistant
required

The built-in assistant is on: show Ask Exhale

boolean
hasHousehold
required

A household exists (made with exhale init); setup only creates the owner’s login

boolean
language

The language to show the signed-in person: their own, else the household’s

string
passwordLoginDisabled
required

Password sign-in is turned off: only show single sign-on

boolean
setupNeedsCode
required

The wizard must ask for the setup code (request not from the server’s machine)

boolean
setupRequired
required

Nobody can sign in yet: show the setup wizard

boolean
sso

Present when single sign-on (OpenID Connect) is enabled; start it by navigating to /api/v1/auth/oidc/start

object
name
required

What the sign-in button says after “Continue with”

string
telegramBot

Username of the Telegram bot, when Telegram is enabled

string
twoFactor

The password was right; send a code to /api/v1/auth/login/two-factor to finish signing in

object
expiresAt
required
string format: date-time
token
required

Send it back with the code; it works for a few minutes

string
user
object
email
required
string
hasPassword
required

The account has a password (accounts made through single sign-on have none)

boolean
id
required
string
locale

The language this person chose; empty: the household’s

string
name
required
string
role
required
string
ssoHost

Host of the identity provider this account is linked to, if any

string

Example 

{
  "$schema": "https://example.com/api/schemas/AuthSession.json"
}

default

Section titled “default”

Error

Media typeapplication/problem+json
object
$schema

A URL to the JSON Schema for this object.

string format: uri
detail

A human-readable explanation specific to this occurrence of the problem.

string
errors

Optional list of individual error details

Array<object> | null
object
location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string
message

Error message text

string
value

The value at the given location

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri
status

HTTP status code

integer format: int64
title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string
type

A URI reference to human-readable documentation for the error.

string format: uri
default: about:blank

Example 

{
  "$schema": "https://example.com/api/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}