Console routes

Sign-in, account, invitations and sessions of the console and the back office (ADR 0015). Generated from openapi.yaml of games-api 0.7.0: 19 routes.

POST /v1/console/sign-in: Sign in with email and password
POST /v1/console/sign-in/totp: Finish a sign-in with the 6-digit code of the authenticator
POST /v1/console/sign-out: Sign out
GET /v1/console/me: The signed-in account
PATCH /v1/console/me: Change the display name
GET /v1/console/invitations/{token}: What an invitation grants, for the accept page
POST /v1/console/invitations/{token}/accept: Accept an invitation; this creates the account and signs it in
POST /v1/console/password/forgot: Email a password reset link
POST /v1/console/password/reset: Set a new password from a reset link
PUT /v1/console/password: Change the password
POST /v1/console/email: Ask to change the email address
POST /v1/console/email/confirm: Confirm a new email address from its link
POST /v1/console/totp: Start a TOTP enrolment
DELETE /v1/console/totp: Remove TOTP, with a current code
POST /v1/console/totp/confirm: Confirm the enrolment with a first code; TOTP is on from here
GET /v1/console/sessions: The account’s sessions, newest first
DELETE /v1/console/sessions/{sessionId}: Revoke one session; revoking the current one signs this browser out
POST /v1/console/impersonation/end: End an impersonation
POST /v1/console/invitation-requests: Ask for an invitation, from the form on developers.filudi.com

POST /v1/console/sign-in

curl -X POST 'https://api.filudi.com/v1/console/sign-in' \
  -H 'content-type: application/json' \
  -d '{
  "email": "you@example.com",
  "password": "string"
}'

const response = await fetch('https://api.filudi.com/v1/console/sign-in', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    email: 'you@example.com',
    password: 'string',
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.filudi.com/v1/console/sign-in',
    json={
        'email': 'you@example.com',
        'password': 'string',
    },
)
response.raise_for_status()
data = response.json()

Sign in with email and password

Sets the filudi_console cookie (ADR 0015). When the account has TOTP, totpRequired is true, me is absent and the cookie holds a pending sign-in for 5 minutes: finish with POST /v1/console/sign-in/totp. An unknown email and a wrong password get the same 401 in the same time. Attempts are limited per email and per IP in Redis, as POST /v1/account/sign-in does.

Credential: none. The route is public.

Request body

application/json, required.

Property	Type	Required	Description
`email`	string (email)	yes
`password`	string	yes	1 to 1024 characters; write only

Responses

Status	Body	Description
200	SignInResult	Signed in, or a TOTP code is due. Headers: `Set-Cookie` (`filudi_console`).
401	Error	“Email or password is wrong.”.
403	none	The account is disabled.
429	Error	Too many requests. Headers: `Retry-After`.
503	none	Redis is down; the rate limit cannot be checked.

POST /v1/console/sign-in/totp

curl -X POST 'https://api.filudi.com/v1/console/sign-in/totp' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com' \
  -H 'content-type: application/json' \
  -d '{
  "code": "string"
}'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/sign-in/totp', {
  method: 'POST',
  credentials: 'include',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    code: 'string',
  }),
});
const data = await response.json();

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.post(
    'https://api.filudi.com/v1/console/sign-in/totp',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
    json={
        'code': 'string',
    },
)
response.raise_for_status()
data = response.json()

Finish a sign-in with the 6-digit code of the authenticator

Needs the pending cookie of POST /v1/console/sign-in. The code is RFC 6238, 30-second step, one step of drift either way; a code is accepted once. The fifth wrong code ends the pending sign-in.

Credential: the console session cookie filudi_console, set by POST /v1/console/sign-in. From a browser, send credentials: 'include'; on a non-GET request the Origin header must be one of the console origins. With X-Filudi-Impersonation: 1 the API reads the filudi_impersonation cookie instead.

Request body

application/json, required.

Property	Type	Required	Description
`code`	TotpCode	yes	Six digits, “123456” or “123 456”; pattern `^[0-9 ]{6,7}$`

Responses

Status	Body	Description
200	ConsoleMe	Signed in; the cookie now holds a 14-day session.
400	Error	Wrong code. On the fifth wrong code the pending sign-in is gone, the cookie is cleared and `details.signInEnded` is true.
401	none	No pending sign-in.

POST `/v1/console/sign-out`

POST /v1/console/sign-out

curl -X POST 'https://api.filudi.com/v1/console/sign-out' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/sign-out', {
  method: 'POST',
  credentials: 'include',
});
// No body: check response.ok.

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.post(
    'https://api.filudi.com/v1/console/sign-out',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
)
response.raise_for_status()
# No body: the status says it all.

Sign out

Deletes the session row and clears the cookie. Answers 204 without a session too.

Responses

Status	Body	Description
204	none	Signed out.

GET `/v1/console/me`

GET /v1/console/me

curl 'https://api.filudi.com/v1/console/me' \
  -b "filudi_console=$FILUDI_SESSION"

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/me', {
  credentials: 'include',
});
const data = await response.json();

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.get(
    'https://api.filudi.com/v1/console/me',
    cookies={'filudi_console': session},
)
response.raise_for_status()
data = response.json()

The signed-in account

Responses

Status	Body	Description
200	ConsoleMe	Account.
401	Error	Missing or invalid token.

PATCH `/v1/console/me`

PATCH /v1/console/me

curl -X PATCH 'https://api.filudi.com/v1/console/me' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com' \
  -H 'content-type: application/json' \
  -d '{
  "name": "string"
}'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/me', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    name: 'string',
  }),
});
const data = await response.json();

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.patch(
    'https://api.filudi.com/v1/console/me',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
    json={
        'name': 'string',
    },
)
response.raise_for_status()
data = response.json()

Change the display name

Request body

application/json, required.

Property	Type	Required	Description
`name`	AccountName	yes	Display name, shown to other members and in the audit log; 1 to 80 characters

Responses

Status	Body	Description
200	ConsoleMe	Account.
400	Error	Validation failed.
401	Error	Missing or invalid token.

GET `/v1/console/invitations/{token}`

GET /v1/console/invitations/{token}

curl 'https://api.filudi.com/v1/console/invitations/string'

const response = await fetch('https://api.filudi.com/v1/console/invitations/string');
const data = await response.json();

import requests

response = requests.get('https://api.filudi.com/v1/console/invitations/string')
response.raise_for_status()
data = response.json()

What an invitation grants, for the accept page

Credential: none. The route is public.

Parameters

Name	In	Type	Required	Description
`token`	path	string	yes	The token of the invitation link

Responses

Status	Body	Description
200	InvitationPreview	Invitation.
404	none	Unknown, expired, accepted or revoked: one answer for the four.

POST `/v1/console/invitations/{token}/accept`

POST /v1/console/invitations/{token}/accept

curl -X POST 'https://api.filudi.com/v1/console/invitations/string/accept' \
  -H 'content-type: application/json' \
  -d '{
  "name": "string",
  "password": "string"
}'

const response = await fetch('https://api.filudi.com/v1/console/invitations/string/accept', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    name: 'string',
    password: 'string',
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.filudi.com/v1/console/invitations/string/accept',
    json={
        'name': 'string',
        'password': 'string',
    },
)
response.raise_for_status()
data = response.json()

Accept an invitation; this creates the account and signs it in

The password follows the policy of PUT /v1/account/password: 8 to 128 characters after NFC normalization, not equal to the email. The token is single use. Sets the filudi_console cookie.

Credential: none. The route is public.

Parameters

Name	In	Type	Required	Description
`token`	path	string	yes	The token of the invitation link

Request body

application/json, required.

Property	Type	Required	Description
`name`	AccountName	yes	Display name, shown to other members and in the audit log; 1 to 80 characters
`password`	NewPassword	yes	The policy of `PUT /v1/account/password`: 8 to 128 characters after NFC normalization, not equal to the email; 8 to 128 characters; write only

Responses

Status	Body	Description
200	ConsoleMe	Account created and signed in. Headers: `Set-Cookie` (`filudi_console`).
400	none	The password breaks the policy.
404	none	Unknown, expired, accepted or revoked.

POST `/v1/console/password/forgot`

POST /v1/console/password/forgot

curl -X POST 'https://api.filudi.com/v1/console/password/forgot' \
  -H 'content-type: application/json' \
  -d '{
  "email": "you@example.com"
}'

const response = await fetch('https://api.filudi.com/v1/console/password/forgot', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    email: 'you@example.com',
  }),
});
// No body: check response.ok.

import requests

response = requests.post(
    'https://api.filudi.com/v1/console/password/forgot',
    json={
        'email': 'you@example.com',
    },
)
response.raise_for_status()
# No body: the status says it all.

Email a password reset link

Answers 202 whether the email is on an account or not. Limited per email and per IP in Redis.

Credential: none. The route is public.

Request body

application/json, required.

Property	Type	Required	Description
`email`	string (email)	yes

Responses

Status	Body	Description
202	none	Sent, or silently not sent.
429	Error	Too many requests. Headers: `Retry-After`.

POST `/v1/console/password/reset`

POST /v1/console/password/reset

curl -X POST 'https://api.filudi.com/v1/console/password/reset' \
  -H 'content-type: application/json' \
  -d '{
  "token": "string",
  "password": "string"
}'

const response = await fetch('https://api.filudi.com/v1/console/password/reset', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    token: 'string',
    password: 'string',
  }),
});
// No body: check response.ok.

import requests

response = requests.post(
    'https://api.filudi.com/v1/console/password/reset',
    json={
        'token': 'string',
        'password': 'string',
    },
)
response.raise_for_status()
# No body: the status says it all.

Set a new password from a reset link

Same policy as PUT /v1/account/password. The token is single use. Other sessions of the account stay signed in.

Credential: none. The route is public.

Request body

application/json, required.

Property	Type	Required	Description
`token`	string	yes
`password`	NewPassword	yes	The policy of `PUT /v1/account/password`: 8 to 128 characters after NFC normalization, not equal to the email; 8 to 128 characters; write only

Responses

Status	Body	Description
204	none	Saved.
400	none	The password breaks the policy.
404	none	Unknown, expired or used token.

PUT `/v1/console/password`

PUT /v1/console/password

curl -X PUT 'https://api.filudi.com/v1/console/password' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com' \
  -H 'content-type: application/json' \
  -d '{
  "current": "string",
  "password": "string"
}'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/password', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    current: 'string',
    password: 'string',
  }),
});
// No body: check response.ok.

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.put(
    'https://api.filudi.com/v1/console/password',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
    json={
        'current': 'string',
        'password': 'string',
    },
)
response.raise_for_status()
# No body: the status says it all.

Change the password

Same policy as PUT /v1/account/password. Other sessions stay signed in.

Request body

application/json, required.

Property	Type	Required	Description
`current`	string	yes	1 to 128 characters; write only
`password`	NewPassword	yes	The policy of `PUT /v1/account/password`: 8 to 128 characters after NFC normalization, not equal to the email; 8 to 128 characters; write only

Responses

Status	Body	Description
204	none	Saved.
400	none	The password breaks the policy.
401	Error	Missing session, or `current` is wrong; then the body carries `details: { field: "current" }`.

POST `/v1/console/email`

POST /v1/console/email

curl -X POST 'https://api.filudi.com/v1/console/email' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com' \
  -H 'content-type: application/json' \
  -d '{
  "password": "string",
  "email": "you@example.com"
}'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/email', {
  method: 'POST',
  credentials: 'include',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    password: 'string',
    email: 'you@example.com',
  }),
});
// No body: check response.ok.

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.post(
    'https://api.filudi.com/v1/console/email',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
    json={
        'password': 'string',
        'email': 'you@example.com',
    },
)
response.raise_for_status()
# No body: the status says it all.

Ask to change the email address

A confirmation link goes to the new address. The account keeps its current email until POST /v1/console/email/confirm.

Request body

application/json, required.

Property	Type	Required	Description
`password`	string	yes	1 to 128 characters; write only
`email`	string (email)	yes

Responses

Status	Body	Description
202	none	Confirmation link sent to the new address.
401	Error	Missing session, or the password is wrong.
409	none	The email is already on an account.

POST `/v1/console/email/confirm`

POST /v1/console/email/confirm

curl -X POST 'https://api.filudi.com/v1/console/email/confirm' \
  -H 'content-type: application/json' \
  -d '{
  "token": "string"
}'

const response = await fetch('https://api.filudi.com/v1/console/email/confirm', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    token: 'string',
  }),
});
// No body: check response.ok.

import requests

response = requests.post(
    'https://api.filudi.com/v1/console/email/confirm',
    json={
        'token': 'string',
    },
)
response.raise_for_status()
# No body: the status says it all.

Confirm a new email address from its link

Credential: none. The route is public.

Request body

application/json, required.

Property	Type	Required	Description
`token`	string	yes

Responses

Status	Body	Description
204	none	Email changed.
404	none	Unknown, expired or used token.
409	none	The email went on another account in the meantime.

POST `/v1/console/totp`

POST /v1/console/totp

curl -X POST 'https://api.filudi.com/v1/console/totp' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/totp', {
  method: 'POST',
  credentials: 'include',
});
const data = await response.json();

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.post(
    'https://api.filudi.com/v1/console/totp',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
)
response.raise_for_status()
data = response.json()

Start a TOTP enrolment

Answers a new secret and its otpauth:// URL for the authenticator app. The secret is not active until POST /v1/console/totp/confirm accepts a code; starting again replaces an unconfirmed secret. Staff without TOTP gets 403 on every /v1/admin/* route except GET /v1/admin/me.

Responses

Status	Body	Description
200	TotpEnrolment	Secret to show once.
401	Error	Missing or invalid token.
409	none	TOTP is already enabled; remove it first.

DELETE `/v1/console/totp`

DELETE /v1/console/totp

curl -X DELETE 'https://api.filudi.com/v1/console/totp' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com' \
  -H 'content-type: application/json' \
  -d '{
  "code": "string"
}'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/totp', {
  method: 'DELETE',
  credentials: 'include',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    code: 'string',
  }),
});
// No body: check response.ok.

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.delete(
    'https://api.filudi.com/v1/console/totp',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
    json={
        'code': 'string',
    },
)
response.raise_for_status()
# No body: the status says it all.

Remove TOTP, with a current code

Request body

application/json, required.

Property	Type	Required	Description
`code`	TotpCode	yes	Six digits, “123456” or “123 456”; pattern `^[0-9 ]{6,7}$`

Responses

Status	Body	Description
204	none	Removed.
400	none	Wrong code.
401	Error	Missing or invalid token.

POST `/v1/console/totp/confirm`

POST /v1/console/totp/confirm

curl -X POST 'https://api.filudi.com/v1/console/totp/confirm' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com' \
  -H 'content-type: application/json' \
  -d '{
  "code": "string"
}'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/totp/confirm', {
  method: 'POST',
  credentials: 'include',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    code: 'string',
  }),
});
// No body: check response.ok.

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.post(
    'https://api.filudi.com/v1/console/totp/confirm',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
    json={
        'code': 'string',
    },
)
response.raise_for_status()
# No body: the status says it all.

Confirm the enrolment with a first code; TOTP is on from here

Request body

application/json, required.

Property	Type	Required	Description
`code`	TotpCode	yes	Six digits, “123456” or “123 456”; pattern `^[0-9 ]{6,7}$`

Responses

Status	Body	Description
204	none	TOTP enabled.
400	none	Wrong code, or no enrolment started.
401	Error	Missing or invalid token.

GET `/v1/console/sessions`

GET /v1/console/sessions

curl 'https://api.filudi.com/v1/console/sessions' \
  -b "filudi_console=$FILUDI_SESSION"

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/sessions', {
  credentials: 'include',
});
const data = await response.json();

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.get(
    'https://api.filudi.com/v1/console/sessions',
    cookies={'filudi_console': session},
)
response.raise_for_status()
data = response.json()

The account’s sessions, newest first

Responses

Status	Body	Description
200	ConsoleSessionInfo[]	Sessions.
401	Error	Missing or invalid token.

DELETE `/v1/console/sessions/{sessionId}`

DELETE /v1/console/sessions/{sessionId}

curl -X DELETE 'https://api.filudi.com/v1/console/sessions/00000000-0000-0000-0000-000000000000' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/sessions/00000000-0000-0000-0000-000000000000', {
  method: 'DELETE',
  credentials: 'include',
});
// No body: check response.ok.

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.delete(
    'https://api.filudi.com/v1/console/sessions/00000000-0000-0000-0000-000000000000',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
)
response.raise_for_status()
# No body: the status says it all.

Revoke one session; revoking the current one signs this browser out

Parameters

Name	In	Type	Required	Description
`sessionId`	path	string (uuid)	yes

Responses

Status	Body	Description
204	none	Revoked.
401	Error	Missing or invalid token.
404	none	Not a session of this account.

POST `/v1/console/impersonation/end`

POST /v1/console/impersonation/end

curl -X POST 'https://api.filudi.com/v1/console/impersonation/end' \
  -b "filudi_console=$FILUDI_SESSION" \
  -H 'origin: https://developers.filudi.com'

// The browser sends the filudi_console cookie and the Origin header itself.
const response = await fetch('https://api.filudi.com/v1/console/impersonation/end', {
  method: 'POST',
  credentials: 'include',
});
// No body: check response.ok.

import requests

# session: the value of the filudi_console cookie set by POST /v1/console/sign-in
response = requests.post(
    'https://api.filudi.com/v1/console/impersonation/end',
    cookies={'filudi_console': session},
    headers={'origin': 'https://developers.filudi.com'},
)
response.raise_for_status()
# No body: the status says it all.

End an impersonation

Send it with X-Filudi-Impersonation: 1. Deletes the impersonation session and clears the filudi_impersonation cookie.

Responses

Status	Body	Description
204	none	Ended.
401	none	No impersonation session.

POST `/v1/console/invitation-requests`

POST /v1/console/invitation-requests

curl -X POST 'https://api.filudi.com/v1/console/invitation-requests' \
  -H 'content-type: application/json' \
  -d '{
  "email": "you@example.com",
  "wants": [
    "games"
  ],
  "message": "string"
}'

const response = await fetch('https://api.filudi.com/v1/console/invitation-requests', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    email: 'you@example.com',
    wants: ['games'],
    message: 'string',
  }),
});
// No body: check response.ok.

import requests

response = requests.post(
    'https://api.filudi.com/v1/console/invitation-requests',
    json={
        'email': 'you@example.com',
        'wants': ['games'],
        'message': 'string',
    },
)
response.raise_for_status()
# No body: the status says it all.

Ask for an invitation, from the form on developers.filudi.com

Stored for staff, who invites or dismisses. No email is sent. 5 requests per IP per day.

Credential: none. The route is public.

Request body

application/json, required. The body is a InvitationRequestInput.

Property	Type	Required	Description
`email`	string (email)	yes	at most 254 characters
`wants`	array of one of `"games"`, `"portals"`	yes	What they build; 1 to 2 items; unique items
`message`	string	yes	Counted after trim; 1 to 500 characters

Responses

Status	Body	Description
202	none	Stored.
400	Error	Validation failed.
429	Error	Too many requests. Headers: `Retry-After`.
503	none	Redis is down; the rate limit cannot be checked.