Authentication

How It Works

Orbit uses Supabase Auth for identity. The frontend obtains a JWT access token from Supabase (via email/password, magic link, or OAuth) and passes it to the API on every request:

Authorization: Bearer <token>

The backend verifies the token signature against the Supabase project's public keys, extracts the user ID, and resolves the corresponding Orbit application user record. If no app user record exists for a valid Supabase identity, one is created automatically on the first request.

Tokens expire according to the Supabase project configuration (typically 1 hour). The frontend is responsible for refreshing the token before it expires using Supabase's client SDK.

---

Endpoints

GET /api/v1/me

Session bootstrap. Call this once on application load to retrieve the current user's profile and determine which parts of the UI to show.

Authentication: Required

Response:

{
  "data": {
    "user": {
      "id": "usr_123",
      "email": "user@example.com",
      "display_name": "Alice Smith",
      "global_role": "STUDENT",
      "status": "ACTIVE"
    },
    "app_state": {
      "requires_role_assignment": false,
      "can_access_dashboard": true
    }
  }
}

app_state fields:

Field	Description
requires_role_assignment	true when the user's global_role is NO_ROLE. Show a role-selection or waiting screen.
can_access_dashboard	true when the user has a role that grants dashboard access (STUDENT, TEACHER, or ADMIN).

---

PATCH /api/v1/me/profile

Update the current user's display name.

Authentication: Required

Request:

{
  "display_name": "Alice Smith"
}

Validation:

• display_name — required string, 1–100 characters.

Response: Returns the updated user object inside the standard data envelope.

---

POST /api/v1/me/delete

Soft-delete the current user's own account. The account is marked as deleted and the user loses access immediately. Data is retained for audit and compliance purposes and is not immediately purged.

Authentication: Required

Request:

{
  "confirmation": "DELETE_MY_ACCOUNT"
}

The confirmation field must be the exact string DELETE_MY_ACCOUNT. Any other value returns a VALIDATION_ERROR.

Blocked conditions:

This endpoint returns PRECONDITION_FAILED in either of the following cases:

• The user is the last global Admin in the system.
• The user is the last Teacher in any class (removing them would leave a class with no teacher).

Resolve either condition before retrying (reassign the admin role or add another teacher to the affected classes).

Response: 204 No Content on success.