Users API

Endpoints for managing user profiles, sessions, and account data. All endpoints in this section require a valid JWT access token, and the authenticated user must match the {userId} route parameter.

Authorization: Bearer {access_token}

Get Profile

GET /api/v1/applications/{applicationId}/users/{userId}/profile

Retrieve the profile of the authenticated user.

Response

200 OK

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "alice@example.com",
    "name": "Alice",
    "avatar_url": "https://example.com/avatar.png",
    "email_verified": true,
    "metadata": {
      "plan": "pro",
      "onboarding_complete": true
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-02-25T12:00:00Z"
  }
}

Error Responses

Update Profile

PUT /api/v1/applications/{applicationId}/users/{userId}/profile

Update the authenticated user's profile fields. All fields are optional; omitted fields are not changed.

Request Body

Response

200 OK

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "alice@example.com",
    "name": "Alice Updated",
    "avatar_url": "https://example.com/new-avatar.png",
    "email_verified": true,
    "metadata": {
      "plan": "enterprise"
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-02-25T13:00:00Z"
  }
}

Error Responses

Change Password

POST /api/v1/applications/{applicationId}/users/{userId}/change-password

Change the authenticated user's password. Requires the current password for verification.

Request Body

Response

200 OK

{
  "data": {
    "message": "Password changed successfully."
  }
}

Error Responses

Delete Account

DELETE /api/v1/applications/{applicationId}/users/{userId}

Soft-delete the authenticated user's account. All refresh tokens are immediately revoked. The user record is retained for audit purposes but cannot log in.

Response

204 No Content

Error Responses

Export Data (GDPR)

GET /api/v1/applications/{applicationId}/users/{userId}/data-export

Export all personal data stored for the user (GDPR Article 15 — Right of Access). Rate limited to 1 request per 60 minutes per user.

Response

200 OK

{
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "alice@example.com",
      "name": "Alice",
      "created_at": "2026-01-01T00:00:00Z"
    },
    "sessions": [...],
    "roles": [...],
    "mfa_methods": [...],
    "oauth_connections": [...],
    "audit_logs": [...]
  }
}

Error Responses

Withdraw Consent

DELETE /api/v1/applications/{applicationId}/users/{userId}/consent

Withdraw all OIDC and OAuth consent grants for the user (GDPR Article 7(3) — Right to Withdraw Consent). Future OAuth flows will require the user to grant consent again.

Response

200 OK

{
  "data": {
    "message": "All consent grants have been withdrawn.",
    "revoked_count": 3
  }
}

List Sessions

GET /api/v1/applications/{applicationId}/users/{userId}/sessions

List all active sessions (non-revoked, non-expired refresh tokens) for the user.

Response

200 OK

{
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "device_info": {
        "ip": "1.2.3.4",
        "user_agent": "Mozilla/5.0 ..."
      },
      "is_remember_me": false,
      "last_used_at": "2026-02-25T12:00:00Z",
      "expires_at": "2026-02-25T13:00:00Z",
      "created_at": "2026-02-25T11:00:00Z"
    }
  ]
}

Error Responses

Revoke Session

DELETE /api/v1/applications/{applicationId}/users/{userId}/sessions/{sessionId}

Revoke a specific session by its ID.

Response

204 No Content

Error Responses

Revoke All Sessions

DELETE /api/v1/applications/{applicationId}/users/{userId}/sessions

Revoke all active sessions for the user. Useful for "log out everywhere" functionality.

Response

200 OK

{
  "data": {
    "revoked_count": 4,
    "message": "Revoked 4 active session(s)."
  }
}

Error Responses