Freedome cloud API (freedome_server) 1.0.0

OUTLINE (03e P2; detailed by 6.CT.1 with 02h). Base https://freedome.nativemind.us/api/v1; /health, /ready, /metrics unversioned. Conventions as the media server (docs/conventions.md): RFC 9457 application/problem+json errors (lowercase-kebab code), cursor pages (limit ≤ 100), Idempotency-Key on creating POSTs, ES256 access JWTs (15 min) + rotating refresh tokens, API keys fdk_ (user / org), fdi_ (installation), fds_ (service). Operations with x-status: planned are not implemented yet (P6) and are excluded from conformance. Support: support@freedome.nativemind.net. Commercial use → https://freedome.nativemind.us/commercial.

Servers: https://freedome.nativemind.us/api/v1 · source openapi/cloud.yaml

discovery · auth · account · api-keys · orgs · registry · enrollment · catalogue · apps

discovery

GET /info — getInfo

Server self-description (product freedome-cloud) · scope anon

Server self-description (product freedome-cloud)

GET /meta — getMeta

Server / contract / schema versions, channel states · scope anon

Server / contract / schema versions, channel states.

GET /.well-known/jwks.json — getJwks

JWKS for access and licence tokens (media servers verify offline) · scope anon

JWKS for access and licence tokens (media servers verify offline)

auth

POST /auth/sign-up — signUp

Create an account (e-mail + password) · scope anon

Create an account (e-mail + password)

Request application/json: {"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":10,"maxLength"

{
  "email": "anna@example.org",
  "password": "correct-horse-battery",
  "client": "native"
}

POST /auth/sign-in — signIn

Sign in (e-mail + password) · scope anon

Sign in (e-mail + password)

Request application/json: {"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1,"maxLength":

{
  "email": "anna@example.org",
  "password": "correct-horse-battery",
  "client": "native"
}

POST /auth/session — createSession

Sign in (02e §5.7 name; alias of signIn) · scope anon

Sign in (02e §5.7 name; alias of signIn)

Request application/json: {"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1,"maxLength":

{
  "email": "anna@example.org",
  "password": "correct-horse-battery"
}

DELETE /auth/session — deleteSession

Sign out the current session (alias of signOut) · scope any

Sign out the current session (alias of signOut)

POST /auth/refresh — refreshSession

Rotate the refresh token (reuse revokes the family) · scope anon

Rotate the refresh token (reuse revokes the family)

Request application/json: {"type":"object","required":[],"properties":{"refreshToken":{"type":"string","minLength":16,"description":"native clients; web clients send the fd_rt cookie"}},

{
  "refreshToken": "example-refresh-token-not-a-secret"
}

POST /auth/sign-out — signOut

Sign out the current session · scope any

Sign out the current session.

POST /auth/sign-out-all — signOutAll

Revoke every session of the account · scope any

Revoke every session of the account.

POST /auth/email/verify — verifyEmail

Confirm the e-mail address with the mailed token · scope anon

Confirm the e-mail address with the mailed token.

Request application/json: {"type":"object","required":["token"],"properties":{"token":{"type":"string","minLength":16}},"additionalProperties":false}

{
  "token": "example-mail-token-not-a-secret"
}

POST /auth/email/verify/resend — resendEmailVerification

Send the verification e-mail again · scope any

Send the verification e-mail again.

POST /auth/password/forgot — forgotPassword

Mail a reset link (no account enumeration) · scope anon

Mail a reset link (no account enumeration)

Request application/json: {"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}},"additionalProperties":false}

{
  "email": "anna@example.org"
}

POST /auth/password/reset — resetPassword

Set a new password with the mailed token (revokes sessions) · scope anon

Set a new password with the mailed token (revokes sessions)

Request application/json: {"type":"object","required":["token","password"],"properties":{"token":{"type":"string","minLength":16},"password":{"type":"string","minLength":10,"writeOnly":t

{
  "token": "example-mail-token-not-a-secret",
  "password": "new-correct-horse"
}

POST /auth/password/change — changePassword

Change the password of the signed-in account · scope any

Change the password of the signed-in account.

Request application/json: {"type":"object","required":["currentPassword","password"],"properties":{"currentPassword":{"type":"string","writeOnly":true},"password":{"type":"string","minLe

{
  "currentPassword": "correct-horse-battery",
  "password": "new-correct-horse"
}

POST /auth/magic-link — requestMagicLink

Mail a one-time sign-in link · scope anon

Mail a one-time sign-in link.

Request application/json: {"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}},"additionalProperties":false}

{
  "email": "anna@example.org"
}

POST /auth/magic-link/verify — verifyMagicLink

Sign in with the magic-link token · scope anon

Sign in with the magic-link token.

Request application/json: {"type":"object","required":["token"],"properties":{"token":{"type":"string","minLength":16}},"additionalProperties":false}

{
  "token": "example-mail-token-not-a-secret"
}

POST /auth/oauth/{provider} — signInWithProvider

Sign in with Apple / Google (provider id token); 503 NOT_CONFIGURED without client ids · scope anon

Sign in with Apple / Google (provider id token); 503 NOT_CONFIGURED without client ids.

Request application/json: {"type":"object","required":["idToken"],"properties":{"idToken":{"type":"string","minLength":16},"nonce":{"type":"string"},"displayName":{"type":"string"},"clie

{
  "idToken": "example.id-token.not-a-secret",
  "nonce": "n-0S6_WzA2Mj"
}

account

GET /me — getAccount

The signed-in account with memberships · scope any

The signed-in account with memberships.

PATCH /me — patchAccount

Merge-patch profile (display name, locale) · scope any

Merge-patch profile (display name, locale)

Request application/merge-patch+json: {"type":"object","minProperties":1,"properties":{"displayName":{"type":"string","maxLength":128},"locale":{"type":"string","maxLength":35}},"additionalPropertie

{
  "displayName": "Anna K."
}

DELETE /me — deleteAccount

Delete the account (7-day grace; 409 while owning an org) · scope any

Delete the account (7-day grace; 409 while owning an org)

POST /me/deletion/cancel — cancelAccountDeletion

Cancel a pending deletion · scope any

Cancel a pending deletion.

GET /me/devices — listAccountDevices

Active logins (refresh-token families) · scope any

Active logins (refresh-token families)

DELETE /me/devices/{sessionId} — deleteAccountDevice

Revoke one login · scope any

Revoke one login.

api-keys

GET /me/api-keys — listAccountApiKeys

List personal API keys · scope any

List personal API keys.

POST /me/api-keys — createAccountApiKey

Create a personal API key (token shown once) · scope any

Create a personal API key (token shown once)

Request application/json: {"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128},"scopes":{"type":"array","minItems":1,"items"

{
  "name": "CI",
  "scopes": [
    "catalogue:read"
  ]
}

DELETE /me/api-keys/{keyId} — deleteAccountApiKey

Revoke a personal API key · scope any

Revoke a personal API key.

GET /orgs/{orgId}/api-keys — listOrgApiKeys

Organisation API keys · scope keys:write

Organisation API keys.

POST /orgs/{orgId}/api-keys — createOrgApiKey

Create an organisation API key (token shown once) · scope keys:write

Create an organisation API key (token shown once)

Request application/json: {"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128},"scopes":{"type":"array","minItems":1,"items"

{
  "name": "CI",
  "scopes": [
    "catalogue:read"
  ]
}

DELETE /orgs/{orgId}/api-keys/{keyId} — deleteOrgApiKey

Revoke an organisation API key · scope keys:write

Revoke an organisation API key.

orgs

GET /orgs — listOrgs

Organisations of the caller · scope any

Organisations of the caller.

POST /orgs — createOrg

Create an organisation (caller = owner) · scope any

Create an organisation (caller = owner)

Request application/json: {"type":"object","required":["name","kind"],"properties":{"name":{"type":"string","minLength":1,"maxLength":128},"kind":{"type":"string"},"country":{"type":"str

{
  "name": "Dome Studio",
  "kind": "studio",
  "country": "RU"
}

GET /orgs/{orgId} — getOrg

Get an organisation (non-members → 404) · scope org:read

Get an organisation (non-members → 404)

PATCH /orgs/{orgId} — patchOrg

Merge-patch an organisation · scope org:write

Merge-patch an organisation.

Request application/merge-patch+json: {"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":128},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"cont

{
  "name": "Dome Studio LLC"
}

DELETE /orgs/{orgId} — deleteOrg

Delete an organisation (owner) · scope org:owner

Delete an organisation (owner)

GET /orgs/{orgId}/members — listOrgMembers

Members · scope org:read

Members.

PATCH /orgs/{orgId}/members/{userId} — patchOrgMember

Change a member role (only owners grant owner) · scope members:write

Change a member role (only owners grant owner)

Request application/merge-patch+json: {"type":"object","required":["role"],"properties":{"role":{"anyOf":[{"enum":["owner","admin","operator","author","viewer"]},{"type":"string","pattern":"^[a-z][a

{
  "role": "admin"
}

DELETE /orgs/{orgId}/members/{userId} — removeOrgMember

Remove a member / leave (at least one owner stays) · scope members:write

Remove a member / leave (at least one owner stays)

GET /orgs/{orgId}/invitations — listOrgInvitations

Pending invitations · scope members:write

Pending invitations.

POST /orgs/{orgId}/invitations — createOrgInvitation

Invite by e-mail (token shown once, 7 days) · scope members:write

Invite by e-mail (token shown once, 7 days)

Request application/json: {"type":"object","required":["email","role"],"properties":{"email":{"type":"string","format":"email"},"role":{"anyOf":[{"enum":["owner","admin","operator","auth

{
  "email": "ivan@example.org",
  "role": "operator"
}

DELETE /orgs/{orgId}/invitations/{invitationId} — revokeOrgInvitation

Revoke an invitation · scope members:write

Revoke an invitation.

POST /invitations/accept — acceptInvitation

Accept an invitation (only by the invited address) · scope any

Accept an invitation (only by the invited address)

Request application/json: {"type":"object","required":["token"],"properties":{"token":{"type":"string","minLength":16}},"additionalProperties":false}

{
  "token": "example-invitation-token-not-a-secret"
}

registry

GET /orgs/{orgId}/venues — listOrgVenues

Venues of the organisation · scope registry:read

Venues of the organisation.

POST /orgs/{orgId}/venues — createOrgVenue

Register a venue · scope registry:write

Register a venue.

Request application/json: {"type":"object","required":["name"],"properties":{"name":{"type":"string"},"address":{"type":"string"},"lat":{"type":"number","minimum":-90,"maximum":90},"lon"

{
  "name": "Planetarium",
  "timezone": "Europe/Moscow",
  "public": true
}

GET /orgs/{orgId}/venues/{venueId} — getOrgVenue

Get a venue · scope registry:read

Get a venue.

PATCH /orgs/{orgId}/venues/{venueId} — patchOrgVenue

Merge-patch a venue · scope registry:write

Merge-patch a venue.

Request application/merge-patch+json: {"type":"object","required":["name"],"properties":{"name":{"type":"string"},"address":{"type":"string"},"lat":{"type":"number","minimum":-90,"maximum":90},"lon"

{
  "name": "Planetarium"
}

DELETE /orgs/{orgId}/venues/{venueId} — deleteOrgVenue

Delete a venue · scope registry:write

Delete a venue.

POST /orgs/{orgId}/venues/{venueId}/domes — createOrgDome

Register a dome in a venue · scope registry:write

Register a dome in a venue.

Request application/json: {"type":"object","required":["name","kind"],"properties":{"name":{"type":"string"},"kind":{"anyOf":[{"enum":["classical","quantum","smartphone"]},{"type":"strin

{
  "name": "Main dome",
  "kind": "classical",
  "diameterM": 8
}

GET /orgs/{orgId}/domes/{domeId} — getOrgDome

Get a dome · scope registry:read

Get a dome.

PATCH /orgs/{orgId}/domes/{domeId} — patchOrgDome

Merge-patch a dome · scope registry:write

Merge-patch a dome.

Request application/merge-patch+json: {"type":"object","required":["name","kind"],"properties":{"name":{"type":"string"},"kind":{"anyOf":[{"enum":["classical","quantum","smartphone"]},{"type":"strin

{
  "name": "Main dome",
  "kind": "classical",
  "tiltDeg": 15
}

DELETE /orgs/{orgId}/domes/{domeId} — deleteOrgDome

Delete a dome · scope registry:write

Delete a dome.

GET /orgs/{orgId}/installations — listOrgInstallations

Installations (media servers) of the organisation · scope registry:read

Installations (media servers) of the organisation.

PATCH /orgs/{orgId}/installations/{installationId} — patchOrgInstallation

Rename / bind to a dome / telemetry level · scope registry:write

Rename / bind to a dome / telemetry level.

Request application/merge-patch+json: {"type":"object","minProperties":1,"properties":{"name":{"type":"string"},"domeId":{"anyOf":[{"description":"Any RFC 9562 UUID, lowercase (e.g. .dome meta.id wr

{
  "telemetryLevel": "full"
}

DELETE /orgs/{orgId}/installations/{installationId} — revokeOrgInstallation

Revoke an installation (its fdi_ key stops working) · scope registry:write

Revoke an installation (its fdi_ key stops working)

GET /orgs/{orgId}/enrollment-tokens — listEnrollmentTokens

Enrollment tokens (headless enrollment) · scope registry:write

Enrollment tokens (headless enrollment)

POST /orgs/{orgId}/enrollment-tokens — createEnrollmentToken

Create an enrollment token (shown once) · scope registry:write

Create an enrollment token (shown once)

Request application/json: {"type":"object","required":[],"properties":{"name":{"type":"string"},"ttlHours":{"type":"integer","minimum":1,"maximum":720}},"additionalProperties":false}

{
  "name": "Bench",
  "ttlHours": 24
}

DELETE /orgs/{orgId}/enrollment-tokens/{tokenId} — revokeEnrollmentToken

Revoke an enrollment token · scope registry:write

Revoke an enrollment token.

enrollment

POST /installations/enroll-requests — createEnrollmentRequest

Media server asks to enroll (RFC 8628 device code) · scope anon

Media server asks to enroll (RFC 8628 device code)

Request application/json: {"type":"object","required":["fingerprintHash","publicKey"],"properties":{"fingerprintHash":{"description":"Lowercase hex SHA-256 digest.","type":"string","patt

{
  "fingerprintHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "publicKey": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
  "name": "Dome 8 m"
}

POST /installations/enroll-requests/token — pollEnrollment

Media server polls with its device code (authorization_pending until approved) · scope anon

Media server polls with its device code (authorization_pending until approved)

Request application/json: {"type":"object","required":["deviceCode"],"properties":{"deviceCode":{"type":"string"},"grantType":{"const":"urn:ietf:params:oauth:grant-type:device_code"}},"a

{
  "deviceCode": "example-device-code-not-a-secret",
  "grantType": "urn:ietf:params:oauth:grant-type:device_code"
}

GET /installations/enroll-requests/{userCode} — getEnrollmentRequest

Show a pending request to the approving user · scope any

Show a pending request to the approving user.

POST /installations/enroll-requests/{userCode}/approve — approveEnrollmentRequest

Approve into an organisation · scope registry:write

Approve into an organisation.

Request application/json: {"type":"object","required":["orgId"],"properties":{"orgId":{"description":"Any RFC 9562 UUID, lowercase (e.g. .dome meta.id written by older tools).","type":"s

{
  "orgId": "0192f3a4-5b6c-7d8e-9f01-23456789c002",
  "name": "Dome 8 m"
}

POST /installations/enroll-requests/{userCode}/deny — denyEnrollmentRequest

Deny a request · scope registry:write

Deny a request.

Request application/json: {"type":"object","properties":{"orgId":{"description":"Any RFC 9562 UUID, lowercase (e.g. .dome meta.id written by older tools).","type":"string","pattern":"^[0

{
  "orgId": "0192f3a4-5b6c-7d8e-9f01-23456789c002",
  "reason": "unknown device"
}

POST /installations/enroll — enrollWithToken

Headless enrollment with an enrollment token · scope anon

Headless enrollment with an enrollment token.

Request application/json: {"type":"object","required":["token","fingerprintHash","publicKey"],"properties":{"token":{"type":"string"},"fingerprintHash":{"description":"Lowercase hex SHA-

{
  "token": "example-enrollment-token-not-a-secret",
  "fingerprintHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "publicKey": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
}

GET /installations/self — getOwnInstallation

The calling installation (fdi_ key) · scope registry:self

The calling installation (fdi_ key)

catalogue

GET /catalogue/items — listCatalogueItems

Content catalogue (planned, P6) · scope catalogue:read · planned

Content catalogue (planned, P6)

GET /catalogue/items/{itemId} — getCatalogueItem

Catalogue item (planned, P6) · scope catalogue:read · planned

Catalogue item (planned, P6)

apps

GET /apps — listApps

Ecosystem app registry (planned, P6) · scope anon · planned

Ecosystem app registry (planned, P6)

NativeMindNONC · commercial use → NativeMind sales · support@freedome.nativemind.net