Side Space

API 参考

Sign-in

7 个接口 · 概览

POST/v1/auth/email/start

Send a 6-digit sign-in code (dev servers accept 000000 and log the code)
无需认证

请求体EmailStartRequest application/json

  • emailstring (email)必填

响应

  • 200
    Code sent
    object
    › 展开字段
    • sentboolean
  • 4xx/5xx
    Error
    Error
请求示例
curl -X POST "https://side.example.com/v1/auth/email/start" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
响应示例 · 200
{
  "sent": false
}

POST/v1/auth/email/verify

Exchange the code for tokens and register this device
无需认证

请求体EmailVerifyRequest application/json

  • emailstring必填
  • codestring必填
    ^[0-9]{6}$
  • device_namestring必填
  • platformstring必填
  • display_namestring
    Used when the account is created

响应

请求示例
curl -X POST "https://side.example.com/v1/auth/email/verify" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","code":"code","device_name":"device_name","platform":"platform"}'
响应示例 · 200
{
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "expires_in": 1,
  "user": {
    "id": "id",
    "email": "[email protected]",
    "display_name": "display_name",
    "kind": "human"
  },
  "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
}

POST/v1/auth/refresh

Rotate the refresh token and get a new access token
无需认证

The refresh token has the form <device_id>.<secret>. Each refresh invalidates the previous refresh token. A revoked device fails immediately with 401.

请求体RefreshRequest application/json

  • refresh_tokenstring必填

响应

请求示例
curl -X POST "https://side.example.com/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"refresh_token"}'
响应示例 · 200
{
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "expires_in": 1,
  "user": {
    "id": "id",
    "email": "[email protected]",
    "display_name": "display_name",
    "kind": "human"
  },
  "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"
}

GET/v1/me

The signed-in user
Bearer 令牌

响应

请求示例
curl "https://side.example.com/v1/me" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "id": "id",
  "email": "[email protected]",
  "display_name": "display_name",
  "kind": "human"
}

GET/v1/releases/{platform}

The newest desktop build for a platform, for the apps' update check (no auth)
无需认证

Set by the server's operator (SIDESPACE_RELEASE__VERSION, _URL, _SHA256, _NOTES, _MIN). With current, the answer says whether that version should update (update) and must (required: older than min_version). 404 when nothing is published for the platform.

参数 · 路径

  • platformstring必填
    macoslinux

参数 · 查询

  • currentstring
    The asking app's version, e.g. 0.1.0

响应

请求示例
curl "https://side.example.com/v1/releases/macos"
响应示例 · 200
{
  "platform": "macos",
  "version": "version",
  "url": "https://hooks.example.com/side",
  "sha256": "sha256",
  "notes": "notes",
  "min_version": "min_version",
  "update": false,
  "required": false
}

GET/v1/devices

My devices
Bearer 令牌

响应

  • 200
    Devices
    object
    › 展开字段
    • itemsDevice[]
      › 6 个字段
      • idstring必填
      • namestring必填
      • platformstring必填
      • last_seen_atTimestamp | any
      • revoked_atTimestamp | any
      • currentboolean必填
请求示例
curl "https://side.example.com/v1/devices" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {
      "id": "id",
      "name": "A001_C003.mov",
      "platform": "platform",
      "last_seen_at": "2026-11-14T09:30:00Z",
      "revoked_at": "2026-11-14T09:30:00Z",
      "current": false
    }
  ]
}

DELETE/v1/devices/{id}

Revoke a device (its refresh token stops working at once)
Bearer 令牌

参数 · 路径

  • idstring必填

响应

  • 204
    Revoked
  • 4xx/5xx
    Error
    Error
请求示例
curl -X DELETE "https://side.example.com/v1/devices/id" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"