[RFD - 0005] - User Management API #195

AleksandarCole · 2024-08-30T10:31:48Z

AleksandarCole
Aug 30, 2024
Maintainer

[RFD - 0005] - User Management API

Authors	State
@darkofabijan @radwo @hamir-suspect @AleksandarCole	`In queue`

What

A new User Management API for Semaphore is the proposed extension of the new v2 api that is currently being built. This API will handle:

Organization management
User administration within organizations
Project-level user access control
User group management

Key features:

CRUD operations for users in organizations and projects
Flexible role assignment (org-level and project-level)
User group creation and management

Why

Scaling issues: As orgs grow, manual user management becomes a bottleneck. This API automates it.
Access control gaps: Current system lacks granularity. New API allows precise permission setting.
Audit nightmares: Tracking who has what access is currently painful. API makes it queryable.
Inflexible structures: Orgs struggle to mirror their team structures in Semaphore. API adds flexibility.
Integration challenges: Users want to connect Semaphore to their IAM systems. API makes this possible.
Cross-project headaches: Managing users across multiple projects is currently tedious. API streamlines this.

Use cases

Dev onboarding automation
- Problem: IT spends hours setting up new devs with correct access.
- Solution: Script uses API to create user, assign to groups, set project access.
- Benefit: Cuts onboarding time, reduces errors.
Consultancy project juggling
- Problem: Constantly changing project teams means constant access updates.
- Solution: API allows dynamic group creation and project assignment.
- Benefit: Access changes in sync with project staffing, minimal manual work.
Compliance reporting
- Problem: Generating access reports for audits is manual and error-prone.
- Solution: Custom tool uses API to pull comprehensive access data.
- Benefit: Accurate, on-demand compliance reports.
Sync with other IAM systems
- Problem: Adding/Removing users form GitHub organization doesn't reflect in Semaphore
- Solution: Custom tool uses API to keep GitHub and Semaphore organizations in sync
- Benefit: Simplify and automate user management.

This API isn't just a nice-to-have. It's addressing real pain points our users face daily. By implementing this, we're not just adding a feature – we're solving critical user management problems and opening up new possibilities for how our users can use and integrate Semaphore in their workflows.

Feature description - API specification

Organizations API

Base URL: https://me.semaphoreci.com/api/v2/organizations

List Organizations

Retrieves a list of all organizations that the authenticated user is a member of.

HTTP Request

GET /organizations

Query Parameters

Parameter	Default	Description
limit	20	The number of organizations to return per page. Maximum value is 100.
offset	0	The number of organizations to skip (used for pagination).

Response

{
  "organizations": [
    {
      "id": "ff19729a-a8d5-4a62-8c5c-9bdbabf6607e",
      "name": "Acme Corp",
      "createdAt": "2023-01-15T10:00:00Z",
      "ownerId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total": 15
}

Describe Organization

Retrieves detailed information about a specific organization.

HTTP Request

GET /organizations/{org_identifier}

Where {org_identifier} can be either the organization name or the organization ID.

Response

{
  "id": "ff19729a-a8d5-4a62-8c5c-9bdbabf6607e",
  "name": "Acme Corp",
  "createdAt": "2023-01-15T10:00:00Z",
  "ownerId": "550e8400-e29b-41d4-a716-446655440000",
  "userCount": 50,
  "projectCount": 10
}

Organization Users API

Base URL: https://me.semaphoreci.com/api/v2/organizations/{org_identifier}

Where {org_identifier} can be either the organization name or the organization ID (e.g., ff19729a-a8d5-4a62-8c5c-9bdbabf6607e).

List Users in Organization

Retrieves a list of all users within a specified organization.

HTTP Request

GET /users

Query Parameters

Parameter	Default	Description
limit	20	The number of users to return per page. Maximum value is 100.
offset	0	The number of users to skip (used for pagination).

Response

{
  "users": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userName": "jane_doe",
      "joinDate": "2023-04-01T12:00:00Z",
      "lastActiveDate": "2024-08-30T09:15:30Z",
      "githubAccount": "janedoe",
      "bitbucketAccount": "jane_doe_bb",
      "organizationRole": "admin",
      "userGroups": ["developers", "team-leads"],
      "projects": [
        {
          "id": "18b40eaf-ce10-49c3-93f2-e4fe72d5160b",
          "name": "Web App",
          "roles": ["admin", "contributor"]
        }
      ]
    }
  ],
  "total": 150
}

Describe User in Organization

Retrieves detailed information about a single user within an organization.

HTTP Request

GET /users/{user_identifier}

Where {user_identifier} can be the user's UUID, GitHub username, or Bitbucket username.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "jane_doe",
  "joinDate": "2023-04-01T12:00:00Z",
  "lastActiveDate": "2024-08-30T09:15:30Z",
  "githubAccount": "janedoe",
  "bitbucketAccount": "jane_doe_bb",
  "organizationRole": "admin",
  "userGroups": ["developers", "team-leads"],
  "projects": [
    {
      "id": "18b40eaf-ce10-49c3-93f2-e4fe72d5160b",
      "name": "Web App",
      "roles": ["admin", "contributor"]
    }
  ]
}

Create User in Organization

Adds a new user to an organization.

HTTP Request

POST /users

Request Body

{
  "userIdentifier": "janedoe",
  "identifierType": "github",
  "organizationRole": "member",
  "groups": ["developers", "frontend-team"],
  "projects": [
    {
      "identifier": "18b40eaf-ce10-49c3-93f2-e4fe72d5160b",
      "roles": ["contributor", "reader"]
    }
  ]
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "jane_doe",
  "joinDate": "2024-08-30T12:00:00Z",
  "lastActiveDate": null,
  "githubAccount": "janedoe",
  "bitbucketAccount": null,
  "organizationRole": "member",
  "userGroups": ["developers", "frontend-team"],
  "projects": [
    {
      "id": "18b40eaf-ce10-49c3-93f2-e4fe72d5160b",
      "name": "Web App",
      "roles": ["contributor", "reader"]
    }
  ]
}

Update User in Organization

Updates an existing user's organization role and/or group memberships within an organization.

HTTP Request

PATCH /users/{user_identifier}

Request Body

{
  "organizationRole": "admin",
  "groups": ["developers", "team-leads", "project-managers"]
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "jane_doe",
  "joinDate": "2023-04-01T12:00:00Z",
  "lastActiveDate": "2024-08-30T09:15:30Z",
  "githubAccount": "janedoe",
  "bitbucketAccount": "jane_doe_bb",
  "organizationRole": "admin",
  "userGroups": ["developers", "team-leads", "project-managers"],
  "projects": [
    {
      "id": "18b40eaf-ce10-49c3-93f2-e4fe72d5160b",
      "name": "Web App",
      "roles": ["admin", "contributor"]
    }
  ]
}

Delete User from Organization

Removes a user from an organization.

HTTP Request

DELETE /users/{user_identifier}

Response

A successful deletion returns an HTTP 204 No Content status.

Error Response

{
  "error": "CannotDeleteUser",
  "message": "User cannot be deleted due to existing responsibilities",
  "details": {
    "reasons": ["OrganizationOwnership", "ProjectOwnership"],
    "organizationName": "Acme Corp",
    "projects": ["Web App", "Mobile App"]
  }
}

Project Users API

Base URL: https://me.semaphoreci.com/api/v2/projects/{project_identifier}

Where {project_identifier} can be either the project name or the project ID (e.g., 18b40eaf-ce10-49c3-93f2-e4fe72d5160b).

List Users in Project

Retrieves a list of all users associated with a specific project.

HTTP Request

GET /users

Query Parameters

Parameter	Default	Description
limit	20	The number of users to return per page. Maximum value is 100.
offset	0	The number of users to skip (used for pagination).

Response

{
  "users": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userName": "jane_doe",
      "roles": ["admin", "contributor", "reader"],
      "roleAssignments": [
        {
          "role": "admin",
          "source": "manual"
        },
        {
          "role": "contributor",
          "source": "repository"
        },
        {
          "role": "reader",
          "source": "user_group"
        }
      ]
    }
  ],
  "total": 25
}

Describe User in Project

Retrieves details of a specific user within a project.

HTTP Request

GET /users/{user_identifier}

Where {user_identifier} can be the user's UUID, GitHub username, or Bitbucket username.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "jane_doe",
  "roles": ["admin", "contributor", "reader"],
  "roleAssignments": [
    {
      "role": "admin",
      "source": "manual"
    },
    {
      "role": "contributor",
      "source": "repository"
    },
    {
      "role": "reader",
      "source": "user_group"
    }
  ]
}

Add User to Project

Adds a user to a project with specified roles.

HTTP Request

POST /users

Request Body

{
  "userIdentifier": "john_smith",
  "roles": ["reader", "contributor"]
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "userName": "john_smith",
  "roles": ["reader", "contributor"],
  "roleAssignments": [
    {
      "role": "reader",
      "source": "manual"
    },
    {
      "role": "contributor",
      "source": "manual"
    }
  ]
}

Update Project User Roles

Updates the roles of a user within a project.

HTTP Request

PATCH /users/{user_identifier}

Request Body

{
  "roles": ["admin", "contributor"]
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userName": "jane_doe",
  "roles": ["admin", "contributor", "reader"],
  "roleAssignments": [
    {
      "role": "admin",
      "source": "manual"
    },
    {
      "role": "contributor",
      "source": "manual"
    },
    {
      "role": "reader",
      "source": "user_group"
    }
  ]
}

Remove User from Project

Removes a user from a project.

HTTP Request

DELETE /users/{user_identifier}

Response

A successful removal returns an HTTP 204 No Content status.

Error Response

{
  "error": "CannotRemoveUser",
  "message": "User cannot be removed from the project",
  "details": {
    "reason": "LastProjectAdmin"
  }
}

Notes on Role Assignment

Organization roles can be: owner, admin, member
Project roles can be: admin, contributor, reader
Role assignment sources can be:
- manual: Roles added directly through the API
- repository: Roles inherited from repository permissions
- user_group: Roles assigned via user group membership
- organization: Roles inherited from the user's organization role
When updating roles, only manually assigned roles can be modified. Roles from other sources (repository, user_group, organization) remain unchanged.

User Groups API - Optional Extended Scope

Base URL: https://me.semaphoreci.com/api/v2/organizations/{org_identifier}/user-groups

Where {org_identifier} can be either the organization name or the organization ID (e.g., ff19729a-a8d5-4a62-8c5c-9bdbabf6607e).

List User Groups

Retrieves a list of all user groups within a specified organization.

HTTP Request

GET /user-groups

Query Parameters

Parameter	Default	Description
limit	20	The number of groups to return per page. Maximum value is 100.
offset	0	The number of groups to skip (used for pagination).

Response

{
  "userGroups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Developers",
      "organizationRole": "member",
      "userCount": 15,
      "projectCount": 3
    }
  ],
  "total": 5
}

Describe User Group

Retrieves detailed information about a specific user group.

HTTP Request

GET /user-groups/{group_identifier}

Where {group_identifier} can be either the group name or the group ID.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Developers",
  "organizationRole": "member",
  "users": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "userName": "jane_doe"
    }
  ],
  "projects": [
    {
      "id": "18b40eaf-ce10-49c3-93f2-e4fe72d5160b",
      "name": "Web App",
      "role": "contributor"
    }
  ]
}

Create User Group

Creates a new user group within the organization.

HTTP Request

POST /user-groups

Request Body

{
  "name": "QA Team",
  "organizationRole": "member"
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "name": "QA Team",
  "organizationRole": "member",
  "userCount": 0,
  "projectCount": 0
}

Update User Group

Updates an existing user group's details.

HTTP Request

PATCH /user-groups/{group_identifier}

Request Body

{
  "name": "QA Team Lead",
  "organizationRole": "admin"
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "name": "QA Team Lead",
  "organizationRole": "admin",
  "userCount": 5,
  "projectCount": 2
}

Delete User Group

Deletes a user group from the organization.

HTTP Request

DELETE /user-groups/{group_identifier}

Response

A successful deletion returns an HTTP 204 No Content status.

Add User to Group

Adds a user to a user group.

HTTP Request

POST /user-groups/{group_identifier}/users

Request Body

{
  "userIdentifier": "john_smith"
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "userName": "john_smith",
  "addedToGroup": true
}

Remove User from Group

Removes a user from a user group.

HTTP Request

DELETE /user-groups/{group_identifier}/users/{user_identifier}

Response

A successful removal returns an HTTP 204 No Content status.

Assign Group to Project

Assigns a user group to a project with a specified role.

HTTP Request

POST /user-groups/{group_identifier}/projects

Request Body

{
  "projectIdentifier": "18b40eaf-ce10-49c3-93f2-e4fe72d5160b",
  "role": "contributor"
}

Response

{
  "groupId": "550e8400-e29b-41d4-a716-446655440002",
  "projectId": "18b40eaf-ce10-49c3-93f2-e4fe72d5160b",
  "projectName": "Web App",
  "role": "contributor",
  "assignedSuccessfully": true
}

Unassign Group from Project

Unassigns a user group from a project.

HTTP Request

DELETE /user-groups/{group_identifier}/projects/{project_identifier}

Response

A successful unassignment returns an HTTP 204 No Content status.

Common Status Codes

Status Code	Description
200	OK -- The request was successful
201	Created -- The user was successfully added to the organization or project
204	No Content -- The user was successfully removed from the organization or project
400	Bad Request -- Invalid input or cannot perform the operation
401	Unauthorized -- Invalid API token
403	Forbidden -- Insufficient permissions
404	Not Found -- Organization, project, or user not found
500	Internal Server Error -- Server error occurred

radwo · 2024-09-11T09:06:47Z

radwo
Sep 11, 2024
Collaborator

Alternative API Proposal for Members/Group Management

This proposal presents an alternative approach for the Members/Group APIs. In this design, we propose using user_id as the sole identifier for users. This forward-looking strategy allows us to decouple from any specific VCS provider, ensuring long-term flexibility.

To address scenarios where users must be identified by their GitHub or Bitbucket login, we suggest leveraging a filter on the Members API list. This would enable retrieval based on VCS information without direct reliance on external providers.

This alternative proposal remains aligned with the guidelines established in our API design guide, ensuring consistency with our existing architecture while offering additional flexibility.

Members API

https://{organization_name}.semaphoreci.com/api/v2/members

Resource format

{
  "apiVersion": "v1",
  "kind": "Member",
  "metadata": {
    "user_id": "f1d8a9b9-1234-4567-89de-9876543210ef",
    "organization_id": "b78c3f9e-4a71-4b1b-88e5-df2a4bb0df5a"
  },
  "spec": {
    "name": "Jane Doe",
    "avatar": "https://example.com/avatar.jpg",
    "roles": [
      {
        "role_id": "6d8f21a4-6f36-4b3c-93a3-9123456789ab",
        "role_name": "Organization Owner",
        "source": "manually_assigned",
        "assigned_at": "2024-09-15T10:30:00Z"
      }
    ],
    "github_account": {
      "id": "6162642",
      "name": "jane-github"
    },
    "bitbucket_account": {
      "id": "{3d87b6e2-45b9-4e7f-b9cd-1a2f3d4b567a}",
      "name": "jane-bitbucket"
    },
    "joining_at": "2023-01-05T08:30:00Z",
    "last_activity_at": "2024-09-05T14:20:00Z"
  }
}

We are omitting emails to prevent potential leaks. Someone could invite every Semaphore user and collect their emails.

Standard Methods

List (+ filter by github/bitbucket login/uid)
Describe by user_id
Delete by user_id

Custom Methods

Invite (github/bitbucket + optional role)
Pending Invitations
AddRole user_id + role
RemoveRole user_id + role

Groups API

https://{organization_name}.semaphoreci.com/api/v2/groups

Resource format

{
  "apiVersion": "v1",
  "kind": "Group",
  "metadata": {
    "organization_id": "b78c3f9e-4a71-4b1b-88e5-df2a4bb0df5a",
    "created_at": "2023-09-01T12:00:00Z",
    "updated_at": "2023-09-05T15:00:00Z"
  },
  "spec": {
    "name": "Developers",
    "slug": "developers",
    "description": "",
    "roles": [
      {
        "role_id": "6d8f21a4-6f36-4b3c-93a3-9123456789ab",
        "role_name": "Member",
        "source": "manually_assigned",
        "assigned_at": "2024-09-15T10:30:00Z"
      }
    ]
  }
}

Standard Methods

List
Create (name + description + role)
Update
Delete

Custom Methods

AddRole
RemoveRole

Group Members API

https://{organization_name}.semaphoreci.com/api/v2/groups/{group_name_or_id}/members

Resource format

{
  "apiVersion": "v1",
  "kind": "GroupMember",
  "metadata": {
    "user_id": "f1d8a9b9-1234-4567-89de-9876543210ef",
    "organization_id": "b78c3f9e-4a71-4b1b-88e5-df2a4bb0df5a",
    "group_id": "b78c3f9e-4a71-4b1b-88e5-df2a4bb0df5a"
  },
  "spec": {
    "name": "Jane Doe",
    "avatar": "https://example.com/avatar.jpg",
    "github_account": {
      "id": "6162642",
      "name": "jane-github"
    },
    "bitbucket_account": {
      "id": "{3d87b6e2-45b9-4e7f-b9cd-1a2f3d4b567a}",
      "name": "jane-bitbucket"
    },
    "joining_at": "2023-01-05T08:30:00Z"
  }
}

Standard Methods

Create user_id
Delete user_id

Project Members

https://{organization_name}.semaphoreci.com/api/v2/projets/{project_name_or_id}/members

Resource format

{
  "apiVersion": "v1",
  "kind": "ProjectMember",
  "metadata": {
    "user_id": "f1d8a9b9-1234-4567-89de-9876543210ef",
    "organization_id": "b78c3f9e-4a71-4b1b-88e5-df2a4bb0df5a",
    "project_id": "b78c3f9e-4a71-4b1b-88e5-df2a4bb0df5a"
  },
  "spec": {
    "name": "Jane Doe",
    "avatar": "https://example.com/avatar.jpg",
    "roles": [
      {
        "role_id": "6d8f21a4-6f36-4b3c-93a3-9123456789ab",
        "role_name": "Contributor",
        "source": "manually_assigned",
        "assigned_at": "2024-09-15T10:30:00Z"
      }
    ],
    "github_account": {
      "id": "6162642",
      "name": "jane-github"
    },
    "bitbucket_account": {
      "id": "{3d87b6e2-45b9-4e7f-b9cd-1a2f3d4b567a}",
      "name": "jane-bitbucket"
    },
    "joining_at": "2023-01-05T08:30:00Z"
  }
}

Standard Methods

List
Describe
Delete

Custom Methods

AddRole (user_id + role_name/slug)
RemoveRole (user_id + role_name/slug)

Project Groups

https://{organization_name}.semaphoreci.com/api/v2/projets/{project_name_or_id}/groups

Resource format

{
  "apiVersion": "v1",
  "kind": "ProjectGroup",
  "metadata": {
    "group_id": "f1d8a9b9-1234-4567-89de-9876543210ef",
    "organization_id": "b78c3f9e-4a71-4b1b-88e5-df2a4bb0df5a",
    "project_id": "b78c3f9e-4a71-4b1b-88e5-df2a4bb0df5a"
  },
  "spec": {
    "name": "Developers",
    "slug": "",
    "description": "",
    "roles": [
      {
        "role_id": "6d8f21a4-6f36-4b3c-93a3-9123456789ab",
        "role_name": "Contributor",
        "source": "manually_assigned",
        "assigned_at": "2024-09-15T10:30:00Z"
      }
    ],
    "joining_at": "2023-01-05T08:30:00Z"
  }
}

Standard Methods

List
Describe
Delete

Custom Methods

AddRole (group_id + role_name/slug)
RemoveRole (group_id + role_name/slug)

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFD - 0005] - User Management API #195

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 1 comment

{{title}}

Select a reply

[RFD - 0005] - User Management API #195

AleksandarCole Aug 30, 2024 Maintainer

[RFD - 0005] - User Management API

What

Why

Use cases

Feature description - API specification

Table of Contents

Organizations API

List Organizations

HTTP Request

Query Parameters

Response

Describe Organization

HTTP Request

Response

Organization Users API

List Users in Organization

HTTP Request

Query Parameters

Response

Describe User in Organization

HTTP Request

Response

Create User in Organization

HTTP Request

Request Body

Response

Update User in Organization

HTTP Request

Request Body

Response

Delete User from Organization

HTTP Request

Response

Error Response

Project Users API

List Users in Project

HTTP Request

Query Parameters

Response

Describe User in Project

HTTP Request

Response

Add User to Project

HTTP Request

Request Body

Response

Update Project User Roles

HTTP Request

Request Body

Response

Remove User from Project

HTTP Request

Response

Error Response

Notes on Role Assignment

User Groups API - Optional Extended Scope

List User Groups

HTTP Request

Query Parameters

Response

Describe User Group

HTTP Request

Response

Create User Group

HTTP Request

Request Body

Response

Update User Group

HTTP Request

Request Body

Response

Delete User Group

HTTP Request

Response

Add User to Group

HTTP Request

Request Body

Response

AleksandarCole
Aug 30, 2024
Maintainer

radwo
Sep 11, 2024
Collaborator