API Response Formats

OAuth Token Response

{
  "access_token": "JWT_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "id_token": "JWT_ID_TOKEN"
}

access_token is used for API authorization. id_token carries identity claims.refresh_token is used to obtain a new access token without re-authentication.

ID Token Claims

{
  "sub": "user-uuid",
  "email": "user@example.com",
  "name": "User Name",
  "email_verified": true,
  "iss": "https://sso.doneisbetter.com",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1234567890,
  "iat": 1234560000
}

App-level permission state is not the same thing as public-user authentication state. If your app depends on per-app access or per-app role, also read the permission APIs.

Public Session Validation

{
  "isValid": true,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "name": "User Name",
    "role": "user",
    "status": "active",
    "emailVerified": true,
    "loginMethods": ["password", "google"]
  }
}

This is the response shape for GET /api/public/session.

Registration Response

{
  "success": true,
  "message": "Registration successful",
  "isAccountLinking": false,
  "loginMethods": ["password"],
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "name": "User Name",
    "role": "user",
    "createdAt": "2026-05-11T10:00:00.000Z"
  }
}

If the email already belongs to a social-only account, the endpoint can return a successful password-linking response instead of creating a new record.

Permission Record Response

{
  "userId": "user-uuid",
  "clientId": "client-uuid",
  "appName": "Launchmass",
  "hasAccess": true,
  "status": "approved",
  "role": "admin",
  "requestedAt": "2026-05-11T10:00:00.000Z",
  "grantedAt": "2026-05-11T10:05:00.000Z",
  "grantedBy": "admin-uuid",
  "createdAt": "2026-05-11T10:00:00.000Z",
  "updatedAt": "2026-05-11T10:05:00.000Z"
}

Canonical permission roles are none, user, admin. Canonical statuses are pending, approved, revoked.

Access Request Response

{
  "message": "Access request created",
  "permission": {
    "userId": "user-uuid",
    "clientId": "client-uuid",
    "appName": "Launchmass",
    "hasAccess": false,
    "status": "pending",
    "role": "none",
    "requestedAt": "2026-05-11T10:00:00.000Z"
  }
}

Error Shapes

OAuth endpoints use RFC-style errors:

{
  "error": "invalid_grant",
  "error_description": "Authorization code expired or invalid"
}

Application endpoints usually use simple JSON error messages:

{
  "error": "Forbidden",
  "message": "Access token client does not match requested client"
}