Onboard a New Team Member

Get a new team member fully set up in ADOC with appropriate access - from sending the invitation email to verifying their permissions work correctly.

Real-World Scenario

Situation: Sarah Chen joins your data engineering team on Monday. She needs:

Access to ADOC for pipeline monitoring
Ability to view production pipelines (but not edit yet)
Access to development environment for testing
Membership in "Data Engineering" team group

Deadline: Ready before her 9 AM start time

Outcome: Sarah logs in Monday morning, sees her team's pipelines, and can start learning the system.

Prerequisites

New hire's work email address
Their team/department name
Their manager's name
Access level needed (viewer, editor, admin)
Admin credentials for ADOC

Step-by-Step Workflow

Step 1: Send Invitation Email

Invite the new team member to create their ADOC account.

API Call

POST /admin/api/users/invite-users

Request

{ "emails": [ "sarah.chen@company.com" ], "groups": ["Data Engineering"], "sendEmail": true, "customMessage": "Welcome to the Data Engineering team! This invitation gives you access to ADOC, our data observability platform. You'll be able to monitor pipelines, view data catalogs, and collaborate with the team. See you Monday!" }

Response

{ "invitations": [ { "email": "sarah.chen@company.com", "status": "SENT", "invitationLink": "https://adoc.company.com/accept-invite?token=abc123xyz", "expiresAt": "2024-12-12T10:00:00Z" } ] }

Checkpoint: Sarah receives email with invitation link

Pro Tip: Send invitations 1-2 days before start date so users can set up accounts on their own schedule.

Step 2: Wait for Account Creation

The new user clicks the invitation link and creates their account by setting a password.

What happens:

User clicks link in email
User sets their password
User completes profile (optional)
Account is activated

You'll know it's done: User will be listed in the system with status "active"

Step 3: Verify User Was Created

Check that the user's account exists and is active.

API Call

GET /admin/api/users/list

Look for in Response

{ "users": [ { "id": "user-301", "email": "sarah.chen@company.com", "firstName": "Sarah", "lastName": "Chen", "enabled": true, "emailVerified": true, "groups": ["Data Engineering"] } ] }

Checkpoint: User appears in list with enabled: true

Save this: user-301 - you'll need this ID for the next steps!

Step 4: Assign Additional Groups (If Needed)

If Sarah needs access to multiple teams or projects, add her to additional groups.

API Call

PUT /admin/api/users/user-301/assign-groups

Path Parameters:

Parameter	Type	Required	Description
userId	string	Yes	The user ID from Step 3 (e.g., `user-301`)

Request

{ "groupIds": [ "group-pipeline-viewers", "group-dev-environment" ] }

Response

{ "success": true, "user": { "id": "user-301", "groups": [ "Data Engineering", "Pipeline Viewers", "Dev Environment Access" ] } }

Common Additional Groups:

Pipeline Viewers - See all pipelines
Dev Environment - Access development resources
Dashboard Users - Access to dashboards
Read Only - View-only across platform

Step 5: Verify Roles Were Assigned

Check that group memberships automatically granted the correct roles.

API Call

GET /authz/api/v1/users/user-301/roles

Path Parameters:

Parameter	Type	Required	Description
userId	string	Yes	The user ID (e.g., `user-301`)

Response

{ "roles": [ { "id": "role-pipeline-viewer", "name": "pipeline-viewer", "description": "View pipelines and runs", "source": "group:Data Engineering" }, { "id": "role-catalog-viewer", "name": "catalog-viewer", "description": "Browse data catalogs", "source": "group:Data Engineering" } ] }

What to check:

User has at least one role
Roles match their job function
No excessive permissions (like admin access)

Step 6: Set User Attributes (Metadata)

Add organizational metadata for HR tracking and access reviews.

API Call

PUT /admin/api/users/user-301

Path Parameters:

Parameter	Type	Required	Description
userId	string	Yes	The user ID (e.g., `user-301`)

Request

{ "firstName": "Sarah", "lastName": "Chen", "email": "sarah.chen@company.com", "attributes": { "department": ["Engineering"], "team": ["Data Engineering"], "level": ["Engineer II"], "manager": ["john.smith@company.com"], "startDate": ["2024-12-09"], "location": ["San Francisco"], "employeeType": ["Full-Time"] } }

Why this matters:

Access reviews: Find all users in a department
Offboarding: Know who their manager is
Auditing: Track when access was granted
Compliance: Employment type affects data access

Step 7: Test Access

Have the user (or you, as admin) test that they can actually access what they need.

Test Checklist

# As the new user, try to: # 1. View pipelines GET /torch-pipeline/api/pipelines/summary # 2. View a specific pipeline GET /torch-pipeline/api/pipelines/15 # 3. View data catalog (if applicable) GET /catalog-server/api/datasets # 4. Cannot create/edit (if they're view-only) PUT /torch-pipeline/api/pipelines # Should fail with 403 Forbidden

Success criteria:

Can access what they need
Cannot access what they shouldn't
No error messages about missing permissions

Complete Onboarding Script

For quick copy-paste onboarding:

# Step 1: Send invitation POST /admin/api/users/invite-users { "emails": ["sarah.chen@company.com"], "groups": ["Data Engineering"], "sendEmail": true } # Step 2: Wait for user to accept (check email) # Step 3: Verify user exists GET /admin/api/users/list # Find user ID (e.g., user-301) # Step 4: Assign additional groups PUT /admin/api/users/user-301/assign-groups { "groupIds": ["group-pipeline-viewers", "group-dev-access"] } # Step 5: Verify roles GET /authz/api/v1/users/user-301/roles # Step 6: Set attributes PUT /admin/api/users/user-301 { "attributes": { "team": ["Data Engineering"], "manager": ["manager@company.com"], "startDate": ["2024-12-09"] } } # Step 7: Test access GET /authz/api/v1/users/permissions?userId=user-301

Common Issues & Solutions

Issue: Invitation email not received

Causes:

Email in spam folder
Typo in email address
Email server delay

Solutions:

Check spam folder
Resend invitation with correct email
Manually send invitation link via Slack

Issue: User can't access pipelines

Causes:

Missing group assignment
Group doesn't have the right role
Domain/resource restrictions

Solutions:

Check groups: GET /admin/api/users/:userId
Check roles: GET /authz/api/v1/users/:userId/roles
Check permissions: GET /authz/api/v1/users/permissions?userId=:userId

Issue: User has too much access

Causes:

Assigned to wrong group
Group has excessive permissions

Solutions:

Remove from incorrect groups
Review group role assignments
Consider creating more granular groups

Bulk Onboarding

Scenario: Onboarding 10+ people at once

See Bulk User Management for:

CSV import workflows
Batch invitation scripts
Template-based onboarding
Automation options

APIs Used

POST /admin/api/users/invite-users - Send invitation
GET /admin/api/users/list - Verify user created
PUT /admin/api/users/:userId/assign-groups - Add to groups
GET /authz/api/v1/users/:userId/roles - Check roles
PUT /admin/api/users/:userId - Set attributes

Last updated on

Was this page helpful?