Team Management

The ONE SDK supports role-based access control for team collaboration. Project owners can invite team members, assign roles, and fine-tune permissions through the dashboard or the Admin API methods on OneEngineClient.

Client Setup

Team management requires admin-level authentication. Use the secretKey to create a server-side client.

import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  baseUrl: process.env.ONE_ENGINE_URL!,
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

Roles

Every team member is assigned one of three roles. Each role has a predefined set of permissions.

Role	Description	Typical use
admin	Full access to all project resources, settings, team management, and billing.	Project owners, lead engineers.
developer	Read and write access to API keys, webhooks, and usage data. Cannot manage team members or billing.	Backend and frontend engineers.
viewer	Read-only access to project data, usage analytics, and webhook logs.	QA, product managers, stakeholders.

Role Comparison Matrix

Capability	admin	developer	viewer
View project settings	Yes	Yes	Yes
Update project settings	Yes	No	No
View API keys	Yes	Yes	No
Regenerate API keys	Yes	Yes	No
View usage analytics	Yes	Yes	Yes
Create webhooks	Yes	Yes	No
Manage webhooks	Yes	Yes	No
View webhook logs	Yes	Yes	Yes
Invite team members	Yes	No	No
Remove team members	Yes	No	No
Change member roles	Yes	No	No
Manage billing	Yes	No	No
Delete project	Yes	No	No

Types

Permission

Defines a single permission granted to a user or role.

interface Permission {
  id: string;
  action: PermissionAction;
  scope: PermissionScope;
  resource?: string;               // Optional resource ID for fine-grained access
}

type PermissionAction =
  | 'read'
  | 'write'
  | 'delete'
  | 'manage';

PermissionScope

Defines the resource scope that a permission applies to.

type PermissionScope =
  | 'project'
  | 'project.settings'
  | 'project.keys'
  | 'project.usage'
  | 'project.webhooks'
  | 'project.team'
  | 'project.billing'
  | 'admin.users'
  | 'admin.projects';

TeamMember

Represents a user within a project team.

interface TeamMember {
  id: string;
  userId: string;
  projectId: string;
  email: string;
  displayName?: string;
  role: 'admin' | 'developer' | 'viewer';
  permissions: Permission[];
  status: 'active' | 'invited' | 'suspended';
  invitedAt: string;               // ISO-8601
  joinedAt?: string;               // ISO-8601, null if still pending
  lastActiveAt?: string;           // ISO-8601
}

Admin Operations

The following OneEngineClient methods provide admin-level user and team management.

Method	Description
adminListUsers(options?)	List all users across the project (admin only).
adminGetUser(userId)	Get detailed info for a specific user.
adminUpdateUser(userId, updates)	Update a user's role, status, or permissions.
adminInviteUser(input)	Invite a new team member by email.
adminRemoveUser(projectId, userId)	Remove a user from the project team.

adminListUsers

List all team members for a project with optional filtering.

interface AdminListUsersOptions {
  projectId: string;
  role?: 'admin' | 'developer' | 'viewer';
  status?: 'active' | 'invited' | 'suspended';
  page?: number;                   // 1-based (default: 1)
  limit?: number;                  // Items per page (default: 20, max: 100)
  search?: string;                 // Search by email or display name
}

const res = await engine.adminListUsers({
  projectId: 'proj_abc123',
  role: 'developer',
  status: 'active',
});

if (res.success) {
  for (const member of res.data) {
    console.log(`${member.email} -- ${member.role} (${member.status})`);
  }
}

adminGetUser

Fetch full details for a single team member including their permissions.

const res = await engine.adminGetUser('usr_xyz789');

if (res.success) {
  const user: TeamMember = res.data;
  console.log('Email:', user.email);
  console.log('Role:', user.role);
  console.log('Status:', user.status);
  console.log('Permissions:');
  for (const perm of user.permissions) {
    console.log(`  ${perm.action} on ${perm.scope}`);
  }
}

adminUpdateUser

Update a team member's role, status, or permissions. Only admins can perform this operation.

interface AdminUpdateUserParams {
  role?: 'admin' | 'developer' | 'viewer';
  status?: 'active' | 'suspended';
  permissions?: Permission[];
  displayName?: string;
}

// Promote a developer to admin
const res = await engine.adminUpdateUser('usr_xyz789', {
  role: 'admin',
});

if (res.success) {
  console.log('Updated role to:', res.data.role);
}

// Suspend a user
const suspendRes = await engine.adminUpdateUser('usr_xyz789', {
  status: 'suspended',
});

if (suspendRes.success) {
  console.log('User suspended:', suspendRes.data.email);
}

Inviting Team Members

From the Dashboard

1. Navigate to your project on dashboard.one23.io.
2. Go to Team in the sidebar.
3. Click Invite Member.
4. Enter the email address and select a role (admin, developer, or viewer).
5. Click Send Invite.

The invitee receives an email with a link to join the project. Their status is invited until they accept.

From the SDK

interface AdminInviteUserInput {
  projectId: string;
  email: string;
  role: 'admin' | 'developer' | 'viewer';
  displayName?: string;
  message?: string;                // Optional personal message in the invite email
}

const res = await engine.adminInviteUser({
  projectId: 'proj_abc123',
  email: 'alice@company.com',
  role: 'developer',
  displayName: 'Alice Chen',
  message: 'Welcome to the team! You have been granted developer access.',
});

if (res.success) {
  console.log('Invite sent to:', res.data.email);
  console.log('Status:', res.data.status);  // 'invited'
  console.log('Invite ID:', res.data.id);
}

Managing Permissions

While roles provide a convenient default set of permissions, admins can assign fine-grained permissions to individual users.

Granting Custom Permissions

const res = await engine.adminUpdateUser('usr_xyz789', {
  role: 'developer',
  permissions: [
    { id: 'perm_1', action: 'read', scope: 'project.settings' },
    { id: 'perm_2', action: 'read', scope: 'project.usage' },
    { id: 'perm_3', action: 'write', scope: 'project.webhooks' },
    { id: 'perm_4', action: 'read', scope: 'project.webhooks' },
    { id: 'perm_5', action: 'read', scope: 'project.keys' },
    { id: 'perm_6', action: 'write', scope: 'project.keys' },
  ],
});

if (res.success) {
  console.log('Custom permissions applied for:', res.data.email);
}

Viewing User Permissions

const res = await engine.adminGetUser('usr_xyz789');

if (res.success) {
  console.log(`Permissions for ${res.data.email} (${res.data.role}):`);

  const grouped = res.data.permissions.reduce((acc, perm) => {
    const key = perm.scope;
    if (!acc[key]) acc[key] = [];
    acc[key].push(perm.action);
    return acc;
  }, {} as Record<string, string[]>);

  for (const [scope, actions] of Object.entries(grouped)) {
    console.log(`  ${scope}: ${actions.join(', ')}`);
  }
}

Removing Team Members

From the Dashboard

Navigate to Team, find the member, click the menu icon, and select Remove from project.

From the SDK

const res = await engine.adminRemoveUser('proj_abc123', 'usr_xyz789');

if (res.success) {
  console.log('User removed from the project.');
}

warning

Removing a team member immediately revokes all their access to the project. If the user has any active sessions, they will receive 403 Forbidden on their next API call.

Full Example

The following script demonstrates inviting a team member, verifying their status, and updating their role after they join.

team-setup.ts

import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  baseUrl: process.env.ONE_ENGINE_URL!,
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

async function onboardTeamMember() {
  const projectId = 'proj_abc123';

  // 1. Invite a new developer
  const inviteRes = await engine.adminInviteUser({
    projectId,
    email: 'bob@company.com',
    role: 'developer',
    displayName: 'Bob Smith',
    message: 'You are invited to collaborate on our trading platform.',
  });

  if (!inviteRes.success) {
    console.error('Invite failed:', inviteRes.error);
    return;
  }

  const memberId = inviteRes.data.id;
  console.log('Invite sent. Member ID:', memberId);

  // 2. List all team members
  const listRes = await engine.adminListUsers({ projectId });

  if (listRes.success) {
    console.log(`\nTeam (${listRes.data.length} members):`);
    for (const member of listRes.data) {
      console.log(`  ${member.email} -- ${member.role} (${member.status})`);
    }
  }

  // 3. Check the invited user's details
  const userRes = await engine.adminGetUser(inviteRes.data.userId);

  if (userRes.success) {
    console.log('\nInvited user details:');
    console.log('  Email:', userRes.data.email);
    console.log('  Role:', userRes.data.role);
    console.log('  Status:', userRes.data.status);
  }

  // 4. After they accept, promote to admin
  // (In practice, you would check userRes.data.status === 'active' first)
  const updateRes = await engine.adminUpdateUser(inviteRes.data.userId, {
    role: 'admin',
  });

  if (updateRes.success) {
    console.log('\nPromoted to admin:', updateRes.data.email);
  }
}

onboardTeamMember();

Next Steps

• Dashboard Overview -- return to the dashboard feature summary.
• API Keys -- manage credentials that team members use.
• Usage & Analytics -- review team activity and API consumption.
• Webhook Configuration -- set up notifications for team events.