Developer Documentation
IntegrationsHelp CenterSign in

Groups

Suggest Edits

📘

Note:

Step 1. Obtain the necessary information

Headers
accept Indicates the types of content the client can accept. I.e. application/scim+json
authorization You will only be able to use Oneflow's SCIM API with a valid SCIM API token. You can create a SCIM API token in the Oneflow web application. See Authentication to learn more.
content-type Indicates the type of data that the client sends to the server. I.e. application/json
Path parameters
GROUP_ID The unique ID of the group inside Oneflow. You can find the group ID using the groups endpoint.
USER_ID The unique ID of the user inside Oneflow. You can find the user ID using the users endpoint.
Query parameters
sortBy
Indicates which field the list of groups will be sorted by. I.e. displayName
sortOrder
Determines the order in which the list of groups will be sorted. I.e. ascending, descending
startIndex
Indicates the starting position in the list as a number. I.e. 1
count
Indicates the total number of records returned in the response. I.e. 100
Body
displayName(required) The name of the group.
externalID The unique ID of the group in your identity provider or application.
id The unique ID of the group inside Oneflow.
schema A schema represents the group's configuration. The schema used varies depending on the request type.
For PATCH requests:
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]
For POST requests:
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"]
members
type Refers to the type of member. This will always be a user.
value The ID of the Oneflow user added to the group. You can find the ID of a user using the users endpoint.
x-ref The URI of the user. You can find the ref URI using the users endpoint.

Step 2. Run the code

Create group

  • To create a group, send a POST request to the Groups endpoint with the SCIM API token in the request’s header.

🚧

Note:

The displayName attribute is mandatory.

curl --request POST \
     --url https://api.oneflow.com/scim/v1/Groups \
     --header 'accept: application/scim+json' \
     --header 'authorization: Bearer  [TOKEN]' \
     --header 'content-type: application/json' \
     --data '
{
  "meta": {
    "resourceType": "Group"
  },
  "members": [
    {
      "type": "User",
      "value": "[USER_ID]",
      "x-ref": "https://api.oneflow.com/scim/v1/Users/[USER_ID]"
    },
    {
      "type": "User",
      "value": "[USER_ID]",
      "x-ref": "https://api.oneflow.com/scim/v1/Users/[USER_ID]"
    }
  ],
  "displayName": "Sales",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ]
}
'

import requests

url = "https://api.oneflow.com/scim/v1/Groups"

payload = {
    "meta": { "resourceType": "Group" },
    "members": [
        {
            "value": "[USER_ID]",
            "type": "User",
            "x-ref": "https://api.oneflow.com/v1/users/[USER_ID]"
        },
        {
            "type": "User",
            "value": "997869",
            "x-ref": "https://api.oneflow.com/v1/users/[USER_ID]"
        }
    ],
    "displayName": "Sales",
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"]
}
headers = {
    "accept": "application/scim+json",
    "content-type": "application/json",
    "authorization": "Bearer [TOKEN]"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

📘

Note:

  • Members attribute
    • The type sub-attribute of the member attribute will always be "User".
    • In the above example, for each value sub-attribute, replace [USER_ID] with the ID of the Oneflow user you include in the group.
    • Note that the type, value, and x-ref details will recur for each user you include in the group.
    • You can get the ID of any user in your account by navigating to Admin > Users.
  • Refer to the Data model for the complete list of SCIM attributes in Oneflow.
  • Once created, you can view the groups in Oneflow by navigating to Admin > Groups.

Get group

  • To get the attributes of a specific group, send a GET request to the Groups endpoint along with their ID as a path parameter.
  • I.e. In the example below, replace [GROUP_ID] with the Oneflow group ID.
curl --request GET \
     --url https://api.oneflow.com/scim/v1/Groups/[GROUP_ID] \
     --header 'accept: application/scim+json' \
     --header 'authorization: Bearer [TOKEN]'

import requests

url = "https://api.oneflow.com/scim/v1/Groups/[GROUP_ID]"

headers = {
    "accept": "application/scim+json",
    "authorization": "Bearer [TOKEN]"
}

response = requests.get(url, headers=headers)
print(response.text)

Update group

❗️

Note

Sending a PUT request will overwrite the entire record. if some fields are omitted from the request, then these will be saved as null.

To avoid data loss, send a GET request first and use this response as the base for the PUT request, or send a PATCH request to partially modify a group record.

  • You can update an existing group by sending a PUT request to the Groups endpoint.
  • To modify one or more group attributes (partially update), send a PATCH request to the Groups endpoint.
  • Include the operation in the op parameter (add, remove, or replace), the attribute you wish to modify in the path parameter, along with its new value. 
curl --request PATCH \
     --url https://api.oneflow.com/scim/v1/Groups/[GROUP_ID] \
     --header 'accept: application/scim+json' \
     --header 'authorization: Bearer [TOKEN]' \
     --header 'content-type: application/json' \
     --data '
{
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Sales"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ]
}
'

import requests

url = "https://api.oneflow.com/scim/v1/Groups/[GROUP_ID]"

payload = { "Operations": [
        {
            "op": "replace",
            "path": "displayName",
            "value": "Sales"
        }
    ],
              "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]
}
headers = {
    "accept": "application/scim+json",
    "content-type": "application/json",
    "authorization": "Bearer [TPKEN]"
}

response = requests.patch(url, json=payload, headers=headers)
print(response.text)

Example response

{
    "displayName": "Sales",
    "externalId": null,
    "id": "237145",
    "members": [
        {
            "$ref": "https://api.oneflow.com/scim/v1/Users/974276",
            "type": "User",
            "value": "974276"
        },
        {
            "$ref": "https://api.oneflow.com/scim/v1/Users/997869",
            "type": "User",
            "value": "997869"
        }
    ],
    "meta": {
        "created": "2023-08-29T10:40:41+00:00",
        "lastModified": "2023-08-29T10:40:41+00:00",
        "location": "https://api.oneflow.com/scim/v1/Groups/237145",
        "resourceType": "Group"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ]
}

List groups

  • You can retrieve the list of Groups in your Oneflow account along with their attributes.
  • To sort or filter the list of groups, use the query parameters specified in the API reference.
  • For instance, to list all groups, send a GET request to the Groups endpoint with the SCIM API token in the request’s header.
curl --request GET 
     --url 'https://api.oneflow.com/scim/v1/Groups?sortOrder=ascending&startIndex=1&count=100' \
     --header 'accept: application/scim+json' \
     --header 'authorization: Bearer [TOKEN]'

import requests

url = "https://api.oneflow.com/scim/v1/Groups?sortOrder=ascending&startIndex=1&count=100"

headers = {
    "accept": "application/scim+json",
    "authorization": "Bearer [TOKEN]"
}

response = requests.get(url, headers=headers)
print(response.text)

Example response

{
    "Resources": [
        {
            "displayName": "Sales",
            "externalId": null,
            "id": "235166",
            "members": [
                {
                    "$ref": "https://api.oneflow.com/scim/v1/Users/947483",
                    "type": "User",
                    "value": "947483"
                },
                {
                    "$ref": "https://api.oneflow.com/scim/v1/Users/949693",
                    "type": "User",
                    "value": "949693"
                },
            ],
            "meta": {
                "created": "2022-05-05T13:59:38+00:00",
                "lastModified": "2023-03-13T13:59:48+00:00",
                "location": "https://api.oneflow.com/scim/v1/Groups/235166",
                "resourceType": "Group"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ]
        },
        {
            "displayName": "Human Resources",
            "externalId": null,
            "id": "236335",
            "members": [
                {
                    "$ref": "https://api.oneflow.com/scim/v1/Users/949693",
                    "type": "User",
                    "value": "949693"
                },
                {
                    "$ref": "https://api.oneflow.com/scim/v1/Users/984948",
                    "type": "User",
                    "value": "984948"
                }
            ],
            "meta": {
                "created": "2023-01-25T17:12:00+00:00",
                "lastModified": "2023-03-13T13:59:54+00:00",
                "location": "https://api.oneflow.com/scim/v1/Groups/236335",
                "resourceType": "Group"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ]
        },
        {
            "displayName": "Marketing",
            "externalId": null,
            "id": "237145",
            "members": [
                {
                    "$ref": "https://api.oneflow.com/scim/v1/Users/974276",
                    "type": "User",
                    "value": "974276"
                },
                {
                    "$ref": "https://api.oneflow.com/scim/v1/Users/997869",
                    "type": "User",
                    "value": "997869"
                }
            ],
            "meta": {
                "created": "2023-08-29T10:40:41+00:00",
                "lastModified": "2023-08-29T10:42:53+00:00",
                "location": "https://api.oneflow.com/scim/v1/Groups/237145",
                "resourceType": "Group"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ]
        }
    ],
    "itemsPerPage": 3,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "startIndex": 3,
    "totalResults": 5
}

Delete group

  • Groups can be deleted by sending a DELETE request to the Groups endpoint with the group ID as a path parameter.
curl --request DELETE \
     --url https://api.oneflow.com/scim/v1/Groups/[GROUP_ID] \
     --header 'authorization: Bearer [TOKEN]'

import requests

url = "https://api.oneflow.com/scim/v1/Groups/[GROUP_ID]"

headers = {"authorization": "Bearer [TOKEN]"}

response = requests.delete(url, headers=headers)
print(response.text)

Response codes

StatusMeaningDescription
200OKOperation completed successfully.
201CreatedReturns the created/updated group, optionally filtered by values in attributes or excludedAttributes parameters.
204No contentThe group was deleted successfully.
400Bad RequestInvalid format or content of the request.
401UnauthorizedThe SCIM token is invalid.
404Not foundThe requested entity is missing.
409ConflictA conflict occurred with the current state of the target resource.

See Handling errors with error codes for reasons and resolutions.

Updated about 1 year ago