User Management Endpoints

User Management Endpoints

The user management endpoints provide comprehensive control over user
accounts, profiles, permissions, and company settings within the
Spartera platform. These endpoints support both individual user
management and company-wide administration.

User Profile Management

Get Current User Profile

Retrieve profile information for the authenticated user.

HTTP

GET /users/me

Get Current User Profile Response

JSON

{
  "data": {
    "user_id": "user_123",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "John Doe",
    "avatar_url": "https://cdn.spartera.com/avatars/user_123.jpg",
    "company": {
      "company_id": "company_456",
      "name": "Analytics Corp",
      "role": "admin"
    },
    "preferences": {
      "timezone": "America/New_York",
      "date_format": "YYYY-MM-DD",
      "currency": "USD",
      "notifications": {
        "email": true,
        "browser": true,
        "mobile": false
      }
    },
    "account_status": "active",
    "last_login": "2025-01-20T14:30:00Z",
    "created_at": "2024-03-15T10:00:00Z",
    "updated_at": "2025-01-18T16:45:00Z"
  }
}

Update User Profile

Update profile information for the authenticated user.

HTTP

PATCH /users/me

Update User Profile Request Body

JSON

{
  "first_name": "Jonathan",
  "last_name": "Doe",
  "display_name": "Jon Doe",
  "preferences": {
    "timezone": "America/Los_Angeles",
    "notifications": {
      "email": true,
      "browser": false,
      "mobile": true
    }
  },
  "bio": "Senior Data Scientist with 10+ years experience"
}

Update User Profile Response

JSON

{
  "data": {
    "user_id": "user_123",
    "first_name": "Jonathan",
    "last_name": "Doe",
    "display_name": "Jon Doe",
    "preferences": {
      "timezone": "America/Los_Angeles",
      "notifications": {
        "email": true,
        "browser": false,
        "mobile": true
      }
    },
    "updated_at": "2025-01-20T18:00:00Z"
  }
}

Upload User Avatar

Upload a new profile picture for the authenticated user.

HTTP

POST /users/me/avatar

Upload User Avatar Request Body (multipart/form-data)

HTTP

avatar: [image file]

Upload User Avatar Response

JSON

{
  "data": {
    "avatar_url": "https://cdn.spartera.com/avatars/user_123_v2.jpg",
    "updated_at": "2025-01-20T18:15:00Z"
  }
}

Company User Management

List Company Users

Get all users associated with a company.

HTTP

GET /companies/{company_id}/users

List Company Users Parameters

• company_id (path, required): Company identifier

List Company Users Query Parameters

• role (optional): Filter by user role
• status (optional): Filter by account status (active, inactive,
  pending)
• search (optional): Search by name or email
• sort (optional): Sort order (name, email, created_at, last_login)
• limit (optional): Results per page (default: 50)
• offset (optional): Pagination offset (default: 0)

List Company Users Response

JSON

{
  "data": [
    {
      "user_id": "user_123",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "display_name": "John Doe",
      "role": "admin",
      "status": "active",
      "permissions": [
        "manage_users",
        "manage_analytics",
        "view_billing",
        "manage_api_keys"
      ],
      "last_login": "2025-01-20T14:30:00Z",
      "created_at": "2024-03-15T10:00:00Z",
      "invited_by": "user_456"
    },
    {
      "user_id": "user_789",
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Smith",
      "display_name": "Jane Smith",
      "role": "analyst",
      "status": "active",
      "permissions": [
        "view_analytics",
        "execute_analytics"
      ],
      "last_login": "2025-01-19T16:22:00Z",
      "created_at": "2024-05-20T14:15:00Z"
    }
  ],
  "meta": {
    "total": 25,
    "active": 23,
    "inactive": 1,
    "pending": 1
  }
}

Invite User to Company

Send an invitation to join the company.

HTTP

POST /companies/{company_id}/users/invite

Invite User to Company Parameters

• company_id (path, required): Company identifier

Invite User to Company Request Body

JSON

{
  "email": "[email protected]",
  "first_name": "New",
  "last_name": "User",
  "role": "analyst",
  "permissions": [
    "view_analytics",
    "execute_analytics"
  ],
  "welcome_message": "Welcome to our analytics team!",
  "send_email": true
}

Invite User to Company Response

JSON

{
  "data": {
    "invitation_id": "invite_123",
    "email": "[email protected]",
    "role": "analyst",
    "status": "sent",
    "expires_at": "2025-02-03T18:30:00Z",
    "invite_url": "https://app.spartera.com/invite/invite_123",
    "sent_at": "2025-01-20T18:30:00Z"
  }
}

Get User Details

Retrieve detailed information about a specific user.

HTTP

GET /companies/{company_id}/users/{user_id}

Get User Details Parameters

• company_id (path, required): Company identifier
• user_id (path, required): User identifier

Get User Details Parameters Response

JSON

{
  "data": {
    "user_id": "user_789",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Smith",
    "display_name": "Jane Smith",
    "avatar_url": "https://cdn.spartera.com/avatars/user_789.jpg",
    "role": "analyst",
    "status": "active",
    "permissions": [
      "view_analytics",
      "execute_analytics"
    ],
    "activity_summary": {
      "last_login": "2025-01-19T16:22:00Z",
      "total_logins": 156,
      "analytics_executions_last_30d": 45,
      "avg_session_duration": "32_minutes"
    },
    "api_usage": {
      "total_requests": 2340,
      "requests_last_30d": 340,
      "favorite_endpoints": [
        "/analytics/assets/asset_123/execute",
        "/marketplace/analytics"
      ]
    },
    "created_at": "2024-05-20T14:15:00Z",
    "invited_by": {
      "user_id": "user_123",
      "name": "John Doe"
    }
  }
}

Update User Permissions

Modify user role and permissions within the company.

HTTP

PATCH /companies/{company_id}/users/{user_id}

Update User Permissions Parameters

• company_id (path, required): Company identifier
• user_id (path, required): User identifier

Update User Permissions Request Body

JSON

{
  "role": "senior_analyst",
  "permissions": [
    "view_analytics",
    "execute_analytics",
    "manage_analytics",
    "view_usage_reports"
  ],
  "status": "active",
  "notes": "Promoted to senior analyst role"
}

Update User Permissions Response

JSON

{
  "data": {
    "user_id": "user_789",
    "role": "senior_analyst",
    "permissions": [
      "view_analytics",
      "execute_analytics", 
      "manage_analytics",
      "view_usage_reports"
    ],
    "status": "active",
    "updated_at": "2025-01-20T19:00:00Z",
    "updated_by": "user_123"
  }
}

Remove User from Company

Remove a user's access to the company.

HTTP

DELETE /companies/{company_id}/users/{user_id}

Remove User from Company Parameters

• company_id (path, required): Company identifier
• user_id (path, required): User identifier

Remove User from Company Query Parameters

• transfer_assets (optional): User ID to transfer owned assets to
• revoke_api_keys (optional): Revoke user's API keys (default: true)

Remove User from Company Response

JSON

{
  "data": {
    "user_id": "user_789",
    "status": "removed",
    "removed_at": "2025-01-20T19:15:00Z",
    "assets_transferred": 3,
    "api_keys_revoked": 2
  }
}

Invitation Management

List Pending Invitations

Get all pending invitations for a company.

HTTP

GET /companies/{company_id}/invitations

List Pending Invitations Parameters

• company_id (path, required): Company identifier

List Pending Invitations Query Parameters

• status (optional): Filter by invitation status (pending, accepted,
  expired)
• role (optional): Filter by invited role

List Pending Invitations Response

JSON

{
  "data": [
    {
      "invitation_id": "invite_123",
      "email": "[email protected]",
      "first_name": "New",
      "last_name": "User",
      "role": "analyst",
      "status": "pending",
      "sent_at": "2025-01-20T18:30:00Z",
      "expires_at": "2025-02-03T18:30:00Z",
      "invited_by": {
        "user_id": "user_123",
        "name": "John Doe"
      },
      "reminder_count": 0
    }
  ],
  "meta": {
    "total": 3,
    "pending": 2,
    "expired": 1
  }
}

Resend Invitation

Send a reminder for a pending invitation.

HTTP

POST /companies/{company_id}/invitations/{invitation_id}/resend

Resend Invitation Parameters

• company_id (path, required): Company identifier
• invitation_id (path, required): Invitation identifier

Resend Invitation Request Body

JSON

{
  "message": "Gentle reminder about joining our analytics team!"
}

Resend Invitation Response

JSON

{
  "data": {
    "invitation_id": "invite_123",
    "email": "[email protected]",
    "status": "resent",
    "sent_at": "2025-01-21T10:00:00Z",
    "reminder_count": 1
  }
}

Cancel Invitation

Cancel a pending invitation.

HTTP

DELETE /companies/{company_id}/invitations/{invitation_id}

Cancel Invitation Parameters

• company_id (path, required): Company identifier
• invitation_id (path, required): Invitation identifier

Cancel Invitation Response

HTTP

204 No Content

Role and Permission Management

List Available Roles

Get all predefined roles and their permissions.

HTTP

GET /companies/{company_id}/roles

List Available Roles Parameters

• company_id (path, required): Company identifier

List Available Roles Response

JSON

{
  "data": [
    {
      "role": "admin",
      "display_name": "Administrator",
      "description": "Full access to all company resources",
      "permissions": [
        "manage_users",
        "manage_analytics",
        "manage_billing",
        "manage_api_keys",
        "view_audit_logs",
        "manage_company_settings"
      ],
      "user_count": 2
    },
    {
      "role": "analyst",
      "display_name": "Data Analyst",
      "description": "Execute analytics and view results",
      "permissions": [
        "view_analytics",
        "execute_analytics",
        "view_own_usage"
      ],
      "user_count": 18
    },
    {
      "role": "viewer",
      "display_name": "Viewer",
      "description": "Read-only access to analytics and reports",
      "permissions": [
        "view_analytics",
        "view_reports"
      ],
      "user_count": 3
    }
  ]
}

Create Custom Role

Create a custom role with specific permissions.

HTTP

POST /companies/{company_id}/roles

Create Custom Role Parameters

• company_id (path, required): Company identifier

Create Custom Role Request Body

JSON

{
  "role": "senior_analyst",
  "display_name": "Senior Data Analyst",
  "description": "Advanced analytics access with limited admin features",
  "permissions": [
    "view_analytics",
    "execute_analytics",
    "manage_analytics",
    "view_usage_reports",
    "mentor_junior_analysts"
  ]
}

Create Custom Role Response

JSON

{
  "data": {
    "role": "senior_analyst",
    "display_name": "Senior Data Analyst",
    "description": "Advanced analytics access with limited admin features",
    "permissions": [
      "view_analytics",
      "execute_analytics",
      "manage_analytics",
      "view_usage_reports",
      "mentor_junior_analysts"
    ],
    "created_at": "2025-01-20T19:30:00Z",
    "created_by": "user_123"
  }
}

Activity and Audit Logs

Get User Activity

Retrieve activity history for a specific user.

HTTP

GET /companies/{company_id}/users/{user_id}/activity

Get User Activity Parameters

• company_id (path, required): Company identifier
• user_id (path, required): User identifier

Get User Activity Query Parameters

• activity_type (optional): Filter by activity type
• start_date (optional): Filter from date
• end_date (optional): Filter to date
• limit (optional): Results per page
• offset (optional): Pagination offset

Get User Activity Response

JSON

{
  "data": [
    {
      "activity_id": "activity_123",
      "user_id": "user_789",
      "activity_type": "analytics_execution",
      "description": "Executed Customer Churn Predictor",
      "details": {
        "asset_id": "asset_123",
        "execution_time_ms": 165,
        "records_processed": 1
      },
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "timestamp": "2025-01-20T17:15:00Z"
    },
    {
      "activity_id": "activity_124",
      "user_id": "user_789", 
      "activity_type": "login",
      "description": "User logged in",
      "details": {
        "session_id": "sess_456",
        "login_method": "email_password"
      },
      "ip_address": "192.168.1.100",
      "timestamp": "2025-01-20T16:45:00Z"
    }
  ],
  "meta": {
    "total": 1247,
    "date_range": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-20T23:59:59Z"
    }
  }
}

User Notifications

Get User Notifications

Retrieve notifications for the authenticated user.

HTTP

GET /users/me/notifications

Get User Notifications Query Parameters

• status (optional): Filter by read/unread status
• type (optional): Filter by notification type
• limit (optional): Results per page
• offset (optional): Pagination offset

Get User Notifications Response

JSON

{
  "data": [
    {
      "notification_id": "notif_123",
      "type": "analytics_complete",
      "title": "Analytics Processing Complete",
      "message": "Your batch analytics job has completed successfully",
      "data": {
        "batch_id": "batch_456",
        "asset_name": "Customer Churn Predictor"
      },
      "status": "unread",
      "created_at": "2025-01-20T18:45:00Z",
      "action_url": "https://app.spartera.com/analytics/batches/batch_456"
    }
  ],
  "meta": {
    "total": 23,
    "unread": 5
  }
}

Mark Notifications as Read

Mark one or more notifications as read.

HTTP

PATCH /users/me/notifications/read

Mark Notifications as Read Request Body

JSON

{
  "notification_ids": ["notif_123", "notif_124"],
  "mark_all": false
}

Mark Notifications as Read Response

JSON

{
  "data": {
    "marked_read": 2,
    "timestamp": "2025-01-20T20:00:00Z"
  }
}

The user management endpoints provide comprehensive control over user
accounts, permissions, and company administration, enabling secure and
efficient team collaboration within the Spartera platform.