Authentication

Users authenticate via OAuth through the Synthetiq Desktop app or CLI. Sessions are managed automatically by the platform.

Current user

GET /api/me

Returns your own identity along with your role and scopes in the active organization. Authentication: User authentication required. No additional scope.

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "Ada Lovelace",
    "avatar_url": "https://…",
    "is_service_account": false,
    "created_at": "2026-01-31T00:00:00Z"
  },
  "is_super_admin": false,
  "organization": {
    "id": "uuid",
    "name": "Acme",
    "slug": "acme",
    "logo_url": null,
    "is_personal": false,
    "member_since": "2026-02-01T00:00:00Z",
    "role": {
      "id": "uuid",
      "name": "Admin",
      "description": "Full control of the organization, including members, roles, billing, settings, and infrastructure.",
      "is_default": true,
      "is_service_role": false
    },
    "scopes": [
      { "id": "uuid", "key": "members:invite", "description": "Invite new members to the organization" }
    ]
  }
}

organization is null when there is no live membership to report — either your token carries no active organization, or it names one you have since been removed from.

Updating your avatar

Your avatar starts as whatever picture your identity provider supplied. To replace it, upload an image and then point your profile at it.

Request an upload URL

POST /api/me/avatar/upload-url

Authentication: User authentication required. No additional scope.

Parameter	Type	Required	Description
`ext`	body	Yes	Image extension: `png`, `jpg`, `jpeg`, `webp`, or `gif`

{
  "uploadUrl": "https://…/storage/v1/object/upload/sign/avatars/…",
  "token": "…",
  "storagePath": "<userId>/1754400000000.png",
  "publicUrl": "https://…/storage/v1/object/public/avatars/<userId>/1754400000000.png"
}

PUT your image bytes to uploadUrl. This does not change your profile on its own. Any avatar you previously uploaded is deleted when you call this.

Point your profile at it

PATCH /api/me

Authentication: User authentication required. No additional scope.

Parameter	Type	Required	Description
`avatar_url`	body	Yes	The `publicUrl` from the upload step. Pass `null` to clear it

{ "avatar_url": "https://…/storage/v1/object/public/avatars/<userId>/1754400000000.png" }

avatar_url must be a URL issued to you by the upload endpoint — arbitrary URLs are rejected, because every client renders this field as an image on member lists and comment threads other people see. Passing null clears your uploaded avatar and falls back to your identity provider’s picture.

Your provider’s picture is recorded once, when your account is first created. Nothing overwrites it afterwards, so signing in again will not revert an avatar you have set.

Your access token carries org_role and org_scopes claims, but those are stamped in when the token is issued and are never revalidated. If your role changes, or someone edits your role’s scopes, the token keeps reporting the old values until it refreshes. Call this endpoint when you need your permissions as they are right now — it reads from the database, not the token.

Route protection

API routes are protected based on the user’s access level within their organization. Each user is assigned a role, and each role contains a set of scopes that determine which operations the user can perform.

Scopes

Scopes are the individual permissions that can be assigned to roles within an organization.

Scope	Grants
`entities:publish`	Create and manage entities
`entities:share`	Share entities with organization members
`entities:share_external`	Share entities with users outside the organization
`entities:share_store`	Publish entities to the organization store
`entities:deploy`	Deploy entities to production infrastructure
`members:invite`	Invite new members to the organization
`members:remove`	Remove members from the organization
`members:manage_roles`	Assign and change roles for organization members
`org:settings`	View and edit organization settings
`org:billing`	Manage organization billing and subscriptions
`org:service-accounts`	Manage service accounts and service roles
`org:trusts`	Manage OIDC trust policies
`infra:provision`	Provision and manage BYOI infrastructure

Platform Docs

Synthetiq Desktop

Synthetiq CLI

App Framework

Services Framework

Workflows Framework

Platform API

Deployments

Authentication

Authentication

Current user

Updating your avatar

Request an upload URL

Point your profile at it

Route protection

Scopes

​Authentication

​Current user

​Updating your avatar

​Request an upload URL

​Point your profile at it

​Route protection

​Scopes

Authentication

Current user

Updating your avatar

Request an upload URL

Point your profile at it

Route protection

Scopes