Creating a new user

Overview

This recipe walks you through the user management lifecycle:

1. Authenticate with the API
2. Create a new user
3. Verify user creation
4. Manage user roles and permissions
5. Resend invitation if needed

Prerequisites

• Valid API token with user management permissions
• Admin or manager role permissions
• Valid email address for the new user

Step 1: Authenticate

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN_HERE

Step 2: Create a New User

Create a user in your Streamline account.

POST /v1/users

Required Fields:

• firstName (string): User's first name
• lastName (string): User's last name
• email (string): Valid email address
• role (string): User role (admin, manager, builder, operator, none)

Request Body:

{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "role": "builder"
}

Response (201 Created):

{
    "id": "89g7d263-ch73-6737-d429-h85550c88d54",
    "fsidUserId": "89g7d263-ch73-6737-d429-h85550c88d54",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "avatarUrl": null,
    "lastLoginAt": null,
    "createdAt": "2024-01-20T14:30:00Z",
    "updatedAt": "2024-01-20T14:30:00Z",
    "isInvite": true,
    "role": "builder",
    "groupNames": [],
    "__fsidPermissions": {
        "api-keys.manage.own": true,
        "api-keys.manage.all": false
    }
}

Important: Save the id from the response - this is the user's unique identifier.

Step 3: Verify User Creation

Check that the user was created successfully by retrieving their details.

GET /v1/users/{id}

Replace {id} with the ID from Step 2.

Response (200 OK):

{
    "id": "89g7d263-ch73-6737-d429-h85550c88d54",
    "fsidUserId": "89g7d263-ch73-6737-d429-h85550c88d54",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "avatarUrl": null,
    "lastLoginAt": null,
    "createdAt": "2024-01-20T14:30:00Z",
    "updatedAt": "2024-01-20T14:30:00Z",
    "isInvite": true,
    "role": "builder",
    "groupNames": [],
    "__fsidPermissions": {
        "api-keys.manage.own": true,
        "api-keys.manage.all": false
    }
}

Step 4: Understanding User Roles

When creating users, you can assign one of these roles:

Step 5: Resend Invitation (Optional)

If the user hasn't received or accepted their invitation, you can resend it.

POST /v1/users/{id}/resend-invitation

Response (204 No Content):
No response body - successful operation.

Step 6: List All Users (Optional)

Verify the user appears in your account's user list.

GET /v1/users

Optional Query Parameters:

• search: Search by name or email
• invitationStatus: Filter by invite or accepted
• pageSize: Number of results per page (default: 50)
• sortField: Sort by field (default: createdAt)

Response (200 OK):

{
    "content": [
        {
            "id": "89g7d263-ch73-6737-d429-h85550c88d54",
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "isInvite": true,
            "role": "builder",
            "createdAt": "2024-01-20T14:30:00Z"
        }
    ],
    "page": {
        "size": 1,
        "pageSize": 50,
        "pageNumber": 1,
        "totalElements": 1,
        "totalPages": 1
    }
}

What Happens Next

After creating a user:

1. Invitation Email: The user receives an email invitation to join your Streamline account
2. Account Setup: They can set their password and complete their profile
3. Role Permissions: They gain access based on their assigned role
4. Team Integration: They can be added to groups and assigned to projects

Common User Management Patterns

Bulk User Creation

1. Create multiple users with the same role
2. Add them to appropriate groups
3. Assign them to relevant projects

User Onboarding Flow

1. Create user with appropriate role
2. Add to relevant groups
3. Assign to starter projects
4. Monitor invitation acceptance

Role-Based Access

1. Create users with specific roles
2. Verify permissions match requirements
3. Update roles as responsibilities change

Error Handling

Common Errors:

422 Validation Error:

{
    "message": "The given data failed to pass validation.",
    "errors": {
        "email": ["The email field is required."],
        "firstName": ["The first name field is required."]
    }
}

Duplicate Email:

{
    "message": "The given data failed to pass validation.",
    "errors": {
        "email": ["The email has already been taken."]
    }
}

Tips

• Use descriptive first and last names for easy identification
• Choose roles carefully based on user responsibilities
• Monitor invitation acceptance and resend if needed
• Use the search functionality to find users quickly
• Consider grouping users by team or department for better organization