> ## Documentation Index
> Fetch the complete documentation index at: https://developers.podero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Team Administration

> Manage staff and admin users within your organization

# Team Administration

Partners can create and manage multiple admin and staff users within their organization to collaborate effectively on device fleet management and customer support.

## User Role Overview

<CardGroup cols={3}>
  <Card title="Admin" icon="user-crown">
    Full access to all organization resources. Can manage other admins and staff.
  </Card>

  <Card title="Staff" icon="user-tie">
    Can view and manage all end-users and devices, but cannot manage other staff or admins.
  </Card>

  <Card title="User" icon="user">
    End-users who can only access their own devices and data.
  </Card>
</CardGroup>

## Adding Staff or Admin Users

<Note>
  Admin and Staff users are created the same way as regular users, but with a different role specified.
</Note>

### Create Admin User

Admins have full access to all organization resources:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {auth_token}' \
    -d '{
      "role": "admin",
      "email": "mycolleague@mycompany.com",
      "first_name": "Jane",
      "last_name": "Smith"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users',
      headers={
          'accept': 'application/json',
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {auth_token}'
      },
      json={
          'role': 'admin',
          'email': 'mycolleague@mycompany.com',
          'first_name': 'Jane',
          'last_name': 'Smith'
      }
  )

  new_admin = response.json()
  print(f"Admin user created: {new_admin['id']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.podero.com/api/partners/v2.0/org/${orgId}/users`,
    {
      method: 'POST',
      headers: {
        'accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${authToken}`
      },
      body: JSON.stringify({
        role: 'admin',
        email: 'mycolleague@mycompany.com',
        first_name: 'Jane',
        last_name: 'Smith'
      })
    }
  );

  const newAdmin = await response.json();
  console.log('Admin user created:', newAdmin.id);
  ```
</CodeGroup>

### Create Staff User

Staff users can manage end-users but not other staff or admins:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {auth_token}' \
    -d '{
      "role": "staff",
      "email": "support@mycompany.com",
      "first_name": "Support",
      "last_name": "Team"
    }'
  ```

  ```python Python theme={null}
  response = requests.post(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users',
      headers={
          'accept': 'application/json',
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {auth_token}'
      },
      json={
          'role': 'staff',
          'email': 'support@mycompany.com',
          'first_name': 'Support',
          'last_name': 'Team'
      }
  )

  new_staff = response.json()
  ```
</CodeGroup>

## Email Invitation Flow

<Steps>
  <Step title="Create User with API">
    When you create an admin or staff user via the API, the user is created in the system.
  </Step>

  <Step title="User Receives Email">
    Your colleague will receive an email invitation to join the platform as an admin or staff member.
  </Step>

  <Step title="User Sets Password">
    They'll use the invitation link to set their password and configure their account.
  </Step>

  <Step title="User Logs In">
    After setting up their account, they can log in and will have the appropriate permissions based on their role.
  </Step>
</Steps>

<Warning>
  Make sure the email address is correct - the invitation will be sent to this address.
</Warning>

## Permission Matrix

### What Each Role Can Do

<Tabs>
  <Tab title="Administrator">
    **Full Access**

    | Action | End-Users | Devices | Staff | Admins |
    | ------ | --------- | ------- | ----- | ------ |
    | Create | ✅         | ✅       | ✅     | ✅      |
    | Read   | ✅         | ✅       | ✅     | ✅      |
    | Update | ✅         | ✅       | ✅     | ✅      |
    | Delete | ✅         | ✅       | ✅     | ✅      |

    Admins can also:

    * Access organization settings
    * Manage API credentials
    * View all audit logs
    * Manage billing (via web portal)
  </Tab>

  <Tab title="Staff">
    **Limited Admin Access**

    | Action | End-Users | Devices | Staff | Admins |
    | ------ | --------- | ------- | ----- | ------ |
    | Create | ✅         | ✅       | ❌     | ❌      |
    | Read   | ✅         | ✅       | ✅     | ✅      |
    | Update | ✅         | ✅       | ❌     | ❌      |
    | Delete | ✅         | ✅       | ❌     | ❌      |

    Staff can:

    * Manage all end-users and their devices
    * Provide customer support
    * View (but not manage) other staff and admins
  </Tab>

  <Tab title="Server-to-Server">
    **API Access**

    Client Credentials (server-to-server) have the same privileges as an Administrator.

    This allows your backend systems to:

    * Automate user and device management
    * Integrate with your internal systems
    * Perform bulk operations
    * Access all organization data
  </Tab>
</Tabs>

## List Team Members

Get all admin and staff users in your organization:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer {auth_token}'
  ```

  ```python Python theme={null}
  response = requests.get(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users',
      headers={
          'accept': 'application/json',
          'Authorization': f'Bearer {auth_token}'
      }
  )

  all_users = response.json()

  # Filter for team members
  team_members = [
      user for user in all_users
      if user['role'] in ['admin', 'staff']
  ]

  print(f"Total team members: {len(team_members)}")
  for member in team_members:
      print(f"  {member['email']} - {member['role']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.podero.com/api/partners/v2.0/org/${orgId}/users`,
    {
      headers: {
        'accept': 'application/json',
        'Authorization': `Bearer ${authToken}`
      }
    }
  );

  const allUsers = await response.json();

  // Filter for team members
  const teamMembers = allUsers.filter(user =>
    ['admin', 'staff'].includes(user.role)
  );

  console.log(`Total team members: ${teamMembers.length}`);
  teamMembers.forEach(member => {
    console.log(`  ${member.email} - ${member.role}`);
  });
  ```
</CodeGroup>

## Update Team Member Role

Change a user's role (requires admin access):

<CodeGroup>
  ```bash cURL theme={null}
  # Promote staff to admin
  curl -X PUT \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {auth_token}' \
    -d '{
      "role": "admin"
    }'
  ```

  ```python Python theme={null}
  # Promote staff to admin
  response = requests.put(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}',
      headers={
          'accept': 'application/json',
          'Content-Type': 'application/json',
          'Authorization': f'Bearer {auth_token}'
      },
      json={'role': 'admin'}
  )

  updated_user = response.json()
  print(f"User role updated to: {updated_user['role']}")
  ```
</CodeGroup>

<Warning>
  Only administrators can change user roles. Staff users cannot promote or demote other users.
</Warning>

## Remove Team Member

Delete a staff or admin user:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer {auth_token}'
  ```

  ```python Python theme={null}
  response = requests.delete(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}',
      headers={
          'accept': 'application/json',
          'Authorization': f'Bearer {auth_token}'
      }
  )

  if response.status_code == 204:
      print("User successfully removed")
  ```
</CodeGroup>

To soft-delete a user — keeping their data intact but revoking access — pass the `soft_delete` query parameter:

```bash theme={null}
curl -X DELETE \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}?soft_delete=true' \
  -H 'Authorization: Bearer {auth_token}'
```

<Note>
  A hard delete (default) removes the user and their data permanently. A soft delete revokes access while retaining their data for audit or re-activation.
</Note>

## Team Member Onboarding Checklist

When adding a new team member, follow this checklist:

<AccordionGroup>
  <Accordion title="1. Determine Role">
    * **Admin**: For managers, senior support staff, or developers who need full access
    * **Staff**: For support team members who work with end-users daily

    Consider the principle of least privilege - start with staff role and upgrade if needed.
  </Accordion>

  <Accordion title="2. Create User Account">
    ```python theme={null}
    new_member = create_user(
        org_id=org_id,
        role='staff',  # or 'admin'
        email='newmember@company.com',
        first_name='John',
        last_name='Doe'
    )
    ```
  </Accordion>

  <Accordion title="3. Verify Email Sent">
    Confirm the team member received the invitation email. Check spam folders if needed.
  </Accordion>

  <Accordion title="4. Account Setup">
    Wait for the team member to complete account setup:

    * Set password
    * Configure profile
    * Accept terms of service
  </Accordion>

  <Accordion title="5. Training & Documentation">
    Provide team members with:

    * Access to this API documentation
    * Your internal procedures and workflows
    * Support escalation paths
    * Access to the Podero utility back-office web app
  </Accordion>

  <Accordion title="6. Verify Access">
    Have the new team member log in and verify they can:

    * Access the organization's users and devices
    * Perform their assigned tasks
    * See appropriate menu options based on their role
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Role Assignment">
    * Use **Staff** role for day-to-day support operations
    * Reserve **Admin** role for managers and senior team members
    * Review roles regularly and adjust as responsibilities change
    * Document why each person has their assigned role
  </Accordion>

  <Accordion title="Security">
    * Use company email addresses only
    * Require strong passwords (enforced by platform)
    * Remove access immediately when team members leave
    * Monitor for suspicious activity
    * Regular audit of active team member accounts
  </Accordion>

  <Accordion title="Collaboration">
    * Use meaningful first/last names for easy identification
    * Create shared documentation for common procedures
    * Establish communication channels for the team
    * Define clear escalation paths for issues
  </Accordion>

  <Accordion title="Access Management">
    * Maintain a list of all team members and their roles
    * Set up offboarding procedures for departing staff
    * Use external\_user\_id to link with HR systems if needed
    * Regularly review and remove inactive accounts
  </Accordion>
</AccordionGroup>

## Common Scenarios

<Tabs>
  <Tab title="New Support Agent">
    **Scenario:** Hiring a new customer support agent

    ```python theme={null}
    # Create staff user for support
    new_agent = create_user(
        org_id=org_id,
        role='staff',
        email='support.agent@company.com',
        first_name='Support',
        last_name='Agent'
    )

    # Agent receives email, sets up account
    # Can now help customers but cannot manage team
    ```
  </Tab>

  <Tab title="Promote to Admin">
    **Scenario:** Promoting a staff member to admin

    ```python theme={null}
    # Staff member has proven capable, promote to admin
    update_user(
        org_id=org_id,
        user_id=staff_user_id,
        role='admin'
    )

    # Notify user of promotion and new responsibilities
    send_notification(
        staff_user_id,
        "You've been promoted to Admin. You now have full access."
    )
    ```
  </Tab>

  <Tab title="Temporary Access">
    **Scenario:** Consultant needs temporary access

    ```python theme={null}
    # Create staff account for consultant
    consultant = create_user(
        org_id=org_id,
        role='staff',
        email='consultant@external.com',
        external_user_id='temp_consultant_2024'
    )

    # Set reminder to remove access after project ends
    schedule_reminder(
        date='2024-12-31',
        action='remove_user',
        user_id=consultant['id']
    )
    ```
  </Tab>

  <Tab title="Team Member Departure">
    **Scenario:** Team member leaves the company

    ```python theme={null}
    # Immediate steps
    delete_user(org_id, departing_user_id)

    # Document and audit
    log_user_removal(
        user_id=departing_user_id,
        reason='Employment terminated',
        date=datetime.now(),
        removed_by=admin_user_id
    )

    # Reassign their responsibilities
    reassign_open_tickets(
        from_user=departing_user_id,
        to_user=replacement_user_id
    )
    ```
  </Tab>
</Tabs>

## Web Portal Access

<Note>
  While the API provides programmatic access, team members should also use the Podero utility back-office web app for day-to-day operations.
</Note>

### Web Portal Features

* **Dashboard**: Overview of all users and devices
* **User Management**: Search, filter, and manage end-users
* **Device Fleet View**: Monitor all connected devices
* **Support Tools**: Quick access to reconnection URLs and troubleshooting
* **Team Management**: View team members (admins can manage)
* **Settings**: Organization configuration and API credentials (admin only)

### Access the Web Portal

* **Production**: [https://app.podero.com/accounts/login/](https://app.podero.com/accounts/login/)
* **Sandbox**: Your unique sandbox subdomain URL

## Next Steps

<CardGroup cols={2}>
  <Card title="User Management" icon="users" href="/partner-api/user-journeys/back-office/user-management">
    Learn about managing end-users
  </Card>

  <Card title="API Reference" icon="book" href="/partner-api/reference/users">
    Complete user parameter reference
  </Card>

  <Card title="Authentication" icon="key" href="/partner-api/overview/authentication">
    Set up API access for your team
  </Card>
</CardGroup>