Creating a new user
A step-by-step guide to create and manage users in Streamline using the API.
Overview
This recipe walks you through the user management lifecycle:
- Authenticate with the API
- Create a new user
- Verify user creation
- Manage user roles and permissions
- 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 namelastName
(string): User's last nameemail
(string): Valid email addressrole
(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:
Role | Description | Typical Permissions |
---|---|---|
admin | Full system access | All permissions including user management |
manager | Team management | User management, project oversight |
builder | Content creation | Create workflows, forms, templates |
operator | Content execution | Run workflows, view reports |
none | Minimal access | Basic viewing permissions |
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 emailinvitationStatus
: Filter byinvite
oraccepted
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:
- Invitation Email: The user receives an email invitation to join your Streamline account
- Account Setup: They can set their password and complete their profile
- Role Permissions: They gain access based on their assigned role
- Team Integration: They can be added to groups and assigned to projects
Common User Management Patterns
Bulk User Creation
- Create multiple users with the same role
- Add them to appropriate groups
- Assign them to relevant projects
User Onboarding Flow
- Create user with appropriate role
- Add to relevant groups
- Assign to starter projects
- Monitor invitation acceptance
Role-Based Access
- Create users with specific roles
- Verify permissions match requirements
- 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
Updated 20 days ago