SCIM API Groups Endpoint

The Groups Endpoints can be used to Manage Agent Groups in the Maestro App via API

Summary of Functions

1. Create Group - POST to BASE_URL/Groups

2. Get Groups - GET to BASE_URL/Groups

3. Get Group By Id - GET to BASE_URL/Groups/:GroupId

4. Modify Group - PUT to BASE_URL/Groups/:GroupId

5. Modify Group - PATCH to BASE_URL/Groups/:GroupId

The Groups Schema

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "string",
    "members": [userIDs|agentIDs|agentEmails],
    "owners": [userIDs]
}

Agent Groups members are agents in the maestroqa app. The Members field can accept emails of agents in the system, userIDs of agents in the system or the externalID of the agents in the system.

The Endpoints

Base URL : https://app.maestroqa.com/api/v1/scim/v2

Create a Group

POST BASE_URL/Groups
Headers: 
apiToken: "<token>" | Authorization: "Basic <encoded token>"
Content-Type: "application/json; charset=utf-8"

Required: schemas, displayName

Body: 
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Group Name",
    "members": ["agent@example.com", "agent2@example.com"],
    "owners": ["abcdefg", "hijklmno"]
}

Response:
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "abcD3fgH1"
    "displayName": "Group Name",
    "members": ["agent@example.com", "agent2@example.com"],
    "owners": ["abcdefg", "hijklmno"]
}

Get all AgentGroups

GET BASE_URL/Groups
Headers: 
apiToken: "<token>" | Authorization: "Basic <encoded token>"
Content-Type: "application/json; charset=utf-8"

Query Parameters:
count - Integer - number of users to return.
startIndex - Integer - offset from 1 to start returning the specified number of users from.

Response:
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": NumberofGroupsinSystem,
    "startIndex": 1,
    "itemsPerPage": 20,
    "Resources": [ array of GroupObjects ]
}

Get Specific AgentGroup

GET BASE_URL/Groups/:id
Headers: 
apiToken: "<token>" | Authorization: "Basic <encoded token>"
Content-Type: "application/json; charset=utf-8"

Response:
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "abcD3fgH1"
    "displayName": "Group Name",
    "members": ["agent@example.com", "agent2@example.com"],
    "owners": [userIDs]
}

Modify an Existing Group

PUT BASE_URL/Groups/:id
Headers: 
apiToken: "<token>" | Authorization: "Basic <encoded token>"
Content-Type: "application/json; charset=utf-8"

Required: schemas
Body: 
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "abcD3fgH1",
    "members": ["agent3@example.com", "agent4@example.com"]
}

Response:
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "abcD3fgH1"
    "displayName": "Group Name",
    "members": ["agent3@example.com", "agent4@example.com"],
    "owners": ["abcdefg", "hijklmno"]
}

PATCH BASE_URL/Groups/:id
Headers: 
apiToken: "<token>" | Authorization: "Basic <encoded token>"
Content-Type: "application/json; charset=utf-8"

Required: schemas
Body: 
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "add | remove | replace",
        "path": "owners | members",
        "value": [
              { "value": "userID" }, 
              { "value": "userID" }  ]
     }]
}

Response:
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 20,
    "Resources": [ array of GroupObjects ]
}