The Users Endpoints can be used to Manage User Accounts in the Maestro App via API
Summary of Functions
Create User - POST to BASE_URL/Users
Get Users - GET to BASE_URL/Users
Get User By Id - GET to BASE_URL/Users/:UserId
Modify/Deactivate/Update User - PUT to BASE_URL/Users/:UserId
Note: Endpoint URLs are case-sensitive
Ex., https://app.maestroqa.com/api/v1/scim/v2/Users -> "Users" must be capitalized to execute a successful request.
Another Note - if attributes are passed via SCIM and are intended to be used as Dates, leverage this format: YYYY-MM-DDT00:00:00.000Z
The User Schema
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": userID
"userName": "username@example.com",
"name": {
"givenName": "<GivenName>",
"familyName": "<FamilyName>"
},
"emails": [{
"value": "username@example.com",
"primary": true
}],
"displayName": "<display name>",
"externalId": "<externalId>",
"groups": [],
"active": true | false,
"roles": ["admin|limitedAdmin|manager|grader|limited_agent|agent"],
"profile": {
"AttributeName": "Value of Attribute",
"AttributeName": “Value of Attribute"
}
}The Endpoints
Base URL : https://app.maestroqa.com/api/v1/scim/v2
Create a User
POST BASE_URL/Users
Headers:
apiToken: "<token>" | Authorization: "Basic <encoded token>"
Content-Type: "application/json; charset=utf-8"
Required: schemas, userName
Body:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "username@example.com",
"name": {
"givenName": "FirstName",
"familyName": "LastName"
},
"emails": [{
"value": "username@example.com",
"primary": true
}],
"displayName": "FirstName LastName",
"active": true,
"roles": ["manager"],
"profile": {
"Title": "Manager",
"Location": “Here"
}
}
Response:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "aBcd3fgH1Jkl"
"userName": "username@example.com",
"name": {
"givenName": "FirstName",
"familyName": "LastName"
},
"emails": [{
"value": "username@example.com",
"primary": true
}],
"externalId": "123456"
"displayName": "FirstName LastName",
"active": true,
"roles": ["manager"],
"profile": {
"Title": "Manager",
"Location": “Here"
}
}
Get Users
GET BASE_URL/Users
Headers:
apiToken: "<token>" | Authorization: "Basic <encoded token>"
Content-Type: "application/json; charset=utf-8"
Optional query Parameters:
count - Integer - number of users to return.
startIndex - Integer - offset from 1 to start returning the specified number of users from.
filter - can be used to find user by userName (email) or userAccessLevel (role).
The filter parameter must include an attribute name followed by an attribute operator, then the desired value.
Example value: userName eq "user@maestroqa.com"
Response:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]
"totalResults": NumberofUsersinSystem,
"startIndex": 1,
"itemsPerPage": 20,
"Resources": [ array of UserObjects ]
}
Sample: Below is a sample on how a "Search" can be performed to look for userName (email) via the https://app.maestroqa.com/api/v1/scim/v2/Users.
1. Looking for a user userName: username@example.com
2. Perform a "Get" Query as below:
https://app.maestroqa.com/api/v1/scim/v2/Users?count=300&startIndex=1&filter=userName eq "username@example.com"
3. The above query would check if there is a userName that exist with the following email "username@example.com".
4. If userName does not exist, the following response would be returned.
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 0,
"startIndex": 1,
"itemsPerPage": 300,
"Resources": []
}
NOTE: The query parameters added to the base URL need to be encoded for the request to work. Below is a sample python script:
import requests
from urllib.parse import urlencode
base_url = 'https://app.maestroqa.com/api/v1/scim/v2/Users'
headers = { 'apitoken': 'APITOKEN' }
query_params = {
'filter': 'userName eq "USER EMAIL"'
}
encoded_query_string = urlencode(query_params)
# Construct the full URL
url = f'{base_url}?{encoded_query_string}'
response = requests.get(url, headers=headers)
# Print the status code
print(f"Status Code: {response.status_code}")
# Print the response body as JSON (if the response is in JSON format)
print(f"Response JSON: {response.json()}")
Get a Specific User by Id
GET BASE_URL/Users/: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:User"],
"id": "aBcd3fgH1Jkl"
"userName": "username@example.com",
"name": {
"givenName": "FirstName",
"familyName": "LastName"
},
"emails": [{
"value": "username@example.com",
"primary": true
}],
"externalId": "123456"
"displayName": "FirstName LastName",
"active": true,
"roles": ["manager"],
"profile": {
"Title": "Manager",
"Location": “Here"
}
}
Modify an Existing User
Send a Payload of parameters in the user schema that should be over written. To delete a user, update "active" to false.
PUT BASE_URL/Users/: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:User"],
"id": "aBcd3fgH1Jkl"
"roles": ["grader"],
"profile": {
"Title": "Grader"
}
}
Response:
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "aBcd3fgH1Jkl"
"userName": "username@example.com",
"name": {
"givenName": "FirstName",
"familyName": "LastName"
},
"emails": [{
"value": "username@example.com",
"primary": true
}],
"externalId": "123456"
"displayName": "FirstName LastName",
"active": true,
"roles": ["grader"],
"profile": {
"Title": "Grader",
"Location": “Here"
}
}