OpenAPI Specification
openapi: 3.0.3
info:
title: BetterCloud Platform Events Groups API
description: The BetterCloud Platform API provides REST API access for managing SaaS application operations, automated workflows, user lifecycle management, and security policies across enterprise SaaS environments. It enables IT and security teams to programmatically manage users, groups, directories, and automation workflows across 100+ integrated SaaS applications.
version: v1
contact:
name: BetterCloud Developer Support
url: https://developer.bettercloud.com/
x-generated-from: documentation
servers:
- url: https://api.bettercloud.com/v1
description: BetterCloud Platform API v1
security:
- apiKeyAuth: []
tags:
- name: Groups
description: Manage groups and group memberships
paths:
/groups:
get:
operationId: listGroups
summary: BetterCloud List Groups
description: Returns a paginated list of groups from integrated directory services.
tags:
- Groups
parameters:
- name: page
in: query
description: Page number.
required: false
schema:
type: integer
default: 1
example: 1
- name: per_page
in: query
description: Results per page.
required: false
schema:
type: integer
default: 25
example: 25
responses:
'200':
description: Paginated list of groups.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupListResponse'
examples:
ListGroups200Example:
summary: Default listGroups 200 response
x-microcks-default: true
value:
data:
- id: group-x1y2z3
name: Engineering Team
email: engineering@example.com
member_count: 45
created_at: '2024-06-01T00:00:00Z'
meta:
page: 1
per_page: 25
total: 20
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createGroup
summary: BetterCloud Create Group
description: Creates a new group in the connected directory service.
tags:
- Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreateRequest'
examples:
CreateGroupRequestExample:
summary: Default createGroup request
x-microcks-default: true
value:
name: New Team
email: newteam@example.com
description: New team group
responses:
'201':
description: Group created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupResponse'
examples:
CreateGroup201Example:
summary: Default createGroup 201 response
x-microcks-default: true
value:
data:
id: group-a9b8c7
name: New Team
email: newteam@example.com
member_count: 0
created_at: '2026-04-19T10:00:00Z'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/groups/{id}:
get:
operationId: getGroup
summary: BetterCloud Get Group
description: Returns a single group with its members.
tags:
- Groups
parameters:
- name: id
in: path
required: true
description: The unique identifier of the group.
schema:
type: string
example: group-x1y2z3
responses:
'200':
description: Group details.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupResponse'
examples:
GetGroup200Example:
summary: Default getGroup 200 response
x-microcks-default: true
value:
data:
id: group-x1y2z3
name: Engineering Team
email: engineering@example.com
member_count: 45
created_at: '2024-06-01T00:00:00Z'
'404':
description: Group not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteGroup
summary: BetterCloud Delete Group
description: Deletes a group from the connected directory service.
tags:
- Groups
parameters:
- name: id
in: path
required: true
description: The unique identifier of the group.
schema:
type: string
example: group-x1y2z3
responses:
'204':
description: Group deleted successfully.
'404':
description: Group not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/groups/{id}/members:
get:
operationId: listGroupMembers
summary: BetterCloud List Group Members
description: Returns the members of a specific group.
tags:
- Groups
parameters:
- name: id
in: path
required: true
description: The unique identifier of the group.
schema:
type: string
example: group-x1y2z3
responses:
'200':
description: List of group members.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMemberListResponse'
examples:
ListGroupMembers200Example:
summary: Default listGroupMembers 200 response
x-microcks-default: true
value:
data:
- user_id: user-a1b2c3d4
email: jsmith@example.com
name: Jane Smith
role: member
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: addGroupMember
summary: BetterCloud Add Group Member
description: Adds a user to a group.
tags:
- Groups
parameters:
- name: id
in: path
required: true
description: The unique identifier of the group.
schema:
type: string
example: group-x1y2z3
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMemberAddRequest'
examples:
AddGroupMemberRequestExample:
summary: Default addGroupMember request
x-microcks-default: true
value:
user_id: user-a1b2c3d4
responses:
'201':
description: Member added successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMemberResponse'
examples:
AddGroupMember201Example:
summary: Default addGroupMember 201 response
x-microcks-default: true
value:
data:
user_id: user-a1b2c3d4
email: jsmith@example.com
role: member
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
GroupCreateRequest:
title: Group Create Request
description: Request body for creating a group.
type: object
required:
- name
properties:
name:
type: string
description: Display name of the group.
example: New Team
email:
type: string
format: email
description: Email address of the group.
example: newteam@example.com
description:
type: string
description: Group description.
example: New team group
GroupMember:
title: Group Member
description: A member of a group.
type: object
properties:
user_id:
type: string
description: Unique identifier of the user.
example: user-a1b2c3d4
email:
type: string
format: email
description: Email of the group member.
example: jsmith@example.com
name:
type: string
description: Display name of the member.
example: Jane Smith
role:
type: string
description: Role in the group.
enum:
- owner
- manager
- member
example: member
GroupMemberResponse:
title: Group Member Response
description: Single group member response.
type: object
properties:
data:
$ref: '#/components/schemas/GroupMember'
GroupMemberAddRequest:
title: Group Member Add Request
description: Request body for adding a member to a group.
type: object
required:
- user_id
properties:
user_id:
type: string
description: ID of the user to add to the group.
example: user-a1b2c3d4
role:
type: string
description: Role to assign in the group.
enum:
- owner
- manager
- member
example: member
GroupMemberListResponse:
title: Group Member List Response
description: List of group members.
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GroupMember'
GroupListResponse:
title: Group List Response
description: Paginated list of groups.
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Group'
meta:
$ref: '#/components/schemas/MetaResponse'
ErrorResponse:
title: Error Response
description: Standard error response from BetterCloud API.
type: object
properties:
code:
type: string
description: Machine-readable error code.
example: RESOURCE_NOT_FOUND
id:
type: string
description: Unique identifier for this error occurrence.
example: err-500123
href:
type: string
description: Link to documentation for this error code.
example: https://developer.bettercloud.com/errors/RESOURCE_NOT_FOUND
reason:
type: string
description: Human-readable explanation of the error.
example: The requested resource was not found
required:
- code
- id
- href
- reason
Group:
title: Group
description: A group from an integrated directory service.
type: object
properties:
id:
type: string
description: Unique identifier for the group.
example: group-x1y2z3
name:
type: string
description: Display name of the group.
example: Engineering Team
email:
type: string
format: email
nullable: true
description: Email address of the group.
example: engineering@example.com
description:
type: string
nullable: true
description: Description of the group.
example: Engineering department group
member_count:
type: integer
description: Number of members in the group.
example: 45
created_at:
type: string
format: date-time
description: When the group was created.
example: '2024-06-01T00:00:00Z'
updated_at:
type: string
format: date-time
nullable: true
description: When the group was last updated.
example: '2026-03-01T00:00:00Z'
GroupResponse:
title: Group Response
description: Single group response.
type: object
properties:
data:
$ref: '#/components/schemas/Group'
MetaResponse:
title: Meta Response
description: Pagination metadata for list responses.
type: object
properties:
page:
type: integer
description: Current page number.
example: 1
per_page:
type: integer
description: Number of items per page.
example: 25
total:
type: integer
description: Total number of items.
example: 150
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key authentication. Provide your BetterCloud API key in the X-API-Key header. Keys can be generated from the BetterCloud developer portal.