Teams

In Cerby, teams are groups of users created to facilitate sharing items, updating roles on items, and provisioning user accounts in seat-based and paid social apps. A team object contains information about the team name, the team type, and the workspace ID.

A team object is created in Cerby when you perform any of the following actions:

• Create a group assignment in your identity provider (IdP), such as Okta and Azure AD, to automatically create a team in Cerby via SCIM.

• Create a self-managed team in Cerby with workspace users.

With the Cerby API, you can retrieve all teams or specific teams by providing their ID. To learn more about teams, refer to the Teams article collection on the Cerby Help Center.

Important: You can only retrieve teams if you have the workspace Admin, Super Admin, or Owner role. Your permissions are determined by your API key based on Cerby’s RBAC system.

List teams

get

With a GET request to the /teams endpoint, you can retrieve the list of all the teams in your workspace.

Important: The API scope required to use this endpoint is: Users data.

Query parameters

page[number]integer · min: 1Optional

The page number to retrieve in the paginated list.

Default: 1

page[size]integer · min: 1 · max: 100Optional

The number of items to return per page.

Default: 25

Responses

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/teams

HTTPcURLJavaScriptPython

GET /api/v1/teams HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": [
    {
      "attributes": {
        "createdAt": "2024-08-06T01:18:45+00:00",
        "name": "acme",
        "type": "user_managed",
        "updatedAt": "2024-08-06T01:18:45+00:00",
        "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
      },
      "id": "5aab889c-1234-4164-87b0-e07e57c12345",
      "type": "team"
    },
    {
      "attributes": {
        "createdAt": "2024-08-06T01:18:45+00:00",
        "name": "general",
        "type": "user_managed",
        "updatedAt": "2024-08-06T01:18:45+00:00",
        "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
      },
      "id": "5aab889c-1234-4164-87b0-e07e57c12345",
      "type": "team"
    },
    {
      "attributes": {
        "createdAt": "2024-08-06T01:18:45+00:00",
        "name": "technical writing",
        "type": "user_managed",
        "updatedAt": "2024-08-06T01:18:45+00:00",
        "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
      },
      "id": "5aab889c-1234-4164-87b0-e07e57c12345",
      "type": "team"
    }
  ],
  "links": {
    "next": "/api/v1/teams?page%5Bnumber%5D=11&page%5Bsize%5D=3",
    "previous": "/api/v1/teams?page%5Bnumber%5D=9&page%5Bsize%5D=3",
    "self": "/api/v1/teams?page%5Bnumber%5D=10&page%5Bsize%5D=3"
  },
  "meta": {
    "page": {
      "maxSize": 100,
      "total": 135
    }
  }
}

Create a team

post

With a POST request to the /teams endpoint, you can create a team in your workspace by providing the team name.

Important: The API scope required to use this endpoint is Write teams.

Body

application/json

Responses

201

The team was successfully created.

application/json

400

Bad request - The server could not interpret the request due to invalid syntax or missing parameters. Review your request and correct it.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

post

/teams

HTTPcURLJavaScriptPython

POST /api/v1/teams HTTP/1.1
Host: my-workspace.cerby.com
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "data": {
    "type": "team",
    "attributes": {
      "name": "Engineering"
    }
  }
}

{
  "data": {
    "attributes": {
      "createdAt": "2024-08-06T01:18:45+00:00",
      "name": "Engineering Team",
      "type": "user_managed",
      "updatedAt": "2024-08-06T01:18:45+00:00",
      "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
    },
    "id": "5aab889c-1234-4164-87b0-e07e57c12345",
    "type": "team"
  }
}

Retrieve a Cerby-managed team by ID

get

With a GET request to the /teams/{id} endpoint, you can retrieve the information of a team by providing its ID.

Important: The API scope required to use this endpoint is: Users data.

Path parameters

idstring · uuidOptional

The unique identifier of the team.

Responses

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/teams/{id}

HTTPcURLJavaScriptPython

GET /api/v1/teams/{id} HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": {
    "attributes": {
      "createdAt": "2024-08-06T01:18:45+00:00",
      "name": "acme",
      "type": "user_managed",
      "updatedAt": "2024-08-06T01:18:45+00:00",
      "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
    },
    "id": "5aab889c-1234-4164-87b0-e07e57c12345",
    "type": "team"
  }
}

Delete a team

delete

With a DELETE request to the /teams/{id} endpoint, you can delete a Cerby-managed team by providing its ID.

Important: The API scope required to use this endpoint is Delete teams.

Path parameters

idstringRequired

The unique identifier of the team.

Responses

204

The team was successfully deleted.

400

Bad request - The server could not interpret the request due to invalid syntax or missing parameters. Review your request and correct it.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

403

Forbidden - User does not have permission to perform this action.

application/json

404

Not found - Resource not found.

application/json

delete

/teams/{id}

HTTPcURLJavaScriptPython

DELETE /api/v1/teams/{id} HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

No content

Update a team

patch

With a PATCH request to the /teams/{id} endpoint, you can update the name of a Cerby-managed team by providing its ID.

Important: The API scope required to use this endpoint is Write teams.

Path parameters

idstringRequired

The unique identifier of the team.

Body

application/json

Responses

200

OK — The updated team JSON object.

application/json

400

Bad request - The server could not interpret the request due to invalid syntax or missing parameters. Review your request and correct it.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

403

Forbidden - User does not have permission to perform this action.

application/json

404

Not found - Resource not found.

application/json

409

Conflict - The request conflicts with the current state of the resource.

application/json

patch

/teams/{id}

HTTPcURLJavaScriptPython

PATCH /api/v1/teams/{id} HTTP/1.1
Host: my-workspace.cerby.com
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "data": {
    "type": "team",
    "attributes": {
      "name": "New Team Name"
    }
  }
}

{
  "data": {
    "id": "5aab889c-1234-4164-87b0-e07e57c12345",
    "type": "team",
    "attributes": {
      "createdAt": "2024-08-06T01:18:45+00:00",
      "name": "New Team Name",
      "type": "user_managed",
      "updatedAt": "2024-08-06T01:18:45+00:00",
      "workspaceId": "1234589c-abcd-abcd-87b0-e07e57c12345"
    }
  }
}

Add members to a team

post

With a POST request to the /teams/{id}/members endpoint, you can add one or more members to a team by providing the team ID and the user IDs.

Important: The API scope required to use this endpoint is Write teams.

Path parameters

idstringRequired

The unique identifier of the team.

Body

application/json

Responses

200

OK.

No content

400

Bad request - The server could not interpret the request due to invalid syntax or missing parameters. Review your request and correct it.

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

post

/teams/{id}/members

HTTPcURLJavaScriptPython

POST /api/v1/teams/{id}/members HTTP/1.1
Host: my-workspace.cerby.com
Content-Type: application/json
Accept: */*
Content-Length: 260

{
  "data": [
    {
      "type": "team_member",
      "attributes": {
        "member_id": "10b258e4-8454-42ac-91a3-cacd42f03220",
        "member_type": "user",
        "role": "admin"
      }
    },
    {
      "type": "team_member",
      "attributes": {
        "member_id": "5fd69061-efc4-4de7-ab52-2ecdd3cc0af6",
        "member_type": "user",
        "role": "admin"
      }
    }
  ]
}

No content