Skip to main content

Outreach SCIM Protocol

Chris
Updated

Outreach SCIM Protocol

The following document describes the Outreach SCIM protocol, which aims to conform to RFC 7643 and RFC 7644.

Notes:

  • This document is subject to change and will be finalized after Beta is complete.

The following content is discussed in this article:

Authentication

Outreach applications use the standard OAuth 2.0 flow.

    • Please see  https://api.outreach.io/api/v2/docs#authentication for more information.
    • The following OAuth scopes are required for SCIM APIs:
      • users.all
      • users.aggregate
      • teams.all
      • profiles.all
      • roles.all
      • scim
    • Note: When the access token has expired and a new set of tokens is requested, the full list of scopes should be included with the request.
    • REQUEST
curl https://api.outreach.io/oauth/token \
  -X POST \
  -d client_id=<Application_Identifier> \
  -d client_secret=<Application_Secret> \
  -d redirect_uri=<Application_Redirect_URI> \
  -d grant_type=refresh_token \
  -d scope=users.all+users.aggregate+teams.all+teams.aggregate+profiles.all+roles.all+scim \
  -d refresh_token=<Refresh_Token>
    • RESPONSE
{
  "access_token": <Access_Token>,
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": <Refresh_Token>,
  "scope": <users.all+users.aggregate+teams.all+teams.aggregate+profiles.all+roles.all+scim>,
  "created_at": 1503308300
}

Rate Limiting and Authorization

The SCIM APIs are subject to the same rate limits as the regular Outreach API rate limits but some of the SCIM requests count as multiple requests towards that limit.  Please see https://api.outreach.io/api/v2/docs#rate-limiting for the general Outreach API rate limits.

Base URI

The Base URI for the Outreach SCIM implementation will be https://api.outreach.io/scim/v2/org_id/ where org_id is the specific Organization GUID as configured in outreach.

ServiceProviderConfig

The following shows a sample request to query for the Service Provider configuration.

Note: There is no org_id required for Service Provider Config API call.

GET /scim/v2/ServiceProviderConfig 
Authorization: Bearer <token>

And an example response follows:

HTTP/1.1 200 OK
Content-Length: 733
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

{
    "authenticationSchemes": [
        {
            "description": "Authentication scheme using the OAuth Bearer Token Standard",
            "documentationUri": "https://api.outreach.io/api/v2/docs#authentication",
            "name": "OAuth Bearer Token",
            "specUri": "http://www.rfc-editor.org/info/rfc6750",
            "type": "oauthbearertoken"
        }
    ],
    "bulk": {
        "supported": false,
        "maxOperations": 0,
        "maxPayloadSize": 0
    },
    "changePassword": {
        "supported": false
    },
    "documentationUri": "https://api.outreach.io/scim/v2/docs",
    "etag": {
        "supported": false
    },
    "filter": {
        "supported": true,
        "maxResults": 1000
    },
    "patch": {
        "supported": true
    },
    "sort": {
        "supported": false
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "meta": {
        "resourceType": "ServiceProviderConfig",
        "created": "2020-10-26T20:28:24Z",
        "location": "https://bento1a.outreach-dev.com/scim/v2/ServiceProviderConfig"
    }
}

Users

Outreach extension to SCIM User

The outreach specific user fields are exposed via a custom schema extension to the regular SCIM User schema

 

The namespace of the outreach schema extension is "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"

 

The following custom fields are available for users:

  1. profileName maps to Outreach Profile Name
  2. roleName maps to Outreach Role Name
  3. custom<N> maps to Outreach custom<N> field.

 

Other fields may be added in the future.

 

Note: the standard SCIM User active property of the user controls the outreach locked property.  Setting active to false locks a user (thereby freeing up any associated license seats).

 

List Users

Users can be enumerated via a GET to the /Users endpoint. This returns the user info using the SCIM ListResponse type.

GET /scim/v2/org_id/Users

Authorization: Bearer <token>

 

HTTP/1.1 200 OK
Content-Length: 696
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
      ],
      "id": "user1",
      "externalId": "external_id1",
      "meta": {
        "resourceType": "User",
        "created": "2020-08-18T14:21:46.57681-07:00",
        "lastModified": "2020-08-18T14:21:46.57681-07:00",
        "location": "https://api.outreach.io/scim/scim/v2/org_id/Users/user1"
      },
      "userName": "user@sso.credentials",
      "name": {
        "familyName": "Doe",
        "givenName": "John"
      },
      "displayName": "John Doe",
      "active": true,
      "emails": [
        {
          "value": "user@sso.credentials",
          "primary": true,
        }
      ]
      "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
        "profileName": "Outreach SDR Profile",
        "roleName": "Sales OPS",
        "custom1": "Custom Field 1",
        "custom2": "Custom Field 2",
        "custom3": "Custom Field 3",
        "custom4": "Custom Field 4",
        "custom5": "Custom Field 5",
      }
    }
  ]
}

Create Users

Users can be created via a POST to the /Users endpoint:

POST /scim/v2/org_id/Users
Authorization: Bearer <token>
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
  ],
  "externalId": "external_id1",
  "meta": {
    "created": "0001-01-01T00:00:00Z",
    "lastModified": "0001-01-01T00:00:00Z"
  },
  "userName": "user@sso.credentials",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "active": true,
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
    "profileName": "Outreach SDR Profile",
    "roleName": "Sales OPS",
    "custom1": "Custom Field 1",
    "custom2": "Custom Field 2",
    "custom3": "Custom Field 3",
    "custom4": "Custom Field 4",
    "custom5": "Custom Field 5",
  }
}

 

And an example response follows:

HTTP/1.1 201 Created
Content-Length: 493
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT
Location: https://api.outreach.io/scim/scim/v2/org_id/Users/user1

 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
  ],
  "id": "user1",
  "externalId": "external_id1",
  "meta": {
    "resourceType": "User",
    "created": "2020-08-18T14:21:46.57681-07:00",
    "lastModified": "2020-08-18T14:21:46.57681-07:00",
    "location": "https://api.outreach.io/scim/scim/v2/org_id/Users/user1"
  },
  "userName": "user@sso.credentials",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "displayName": "John Doe",
  "emails": [
    {
      "value": "user@sso.credentials",
      "primary": true,
    }
  ]
  "active": true,
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
    "profileName": "Outreach SDR Profile",
    "roleName": "Sales OPS",
    "custom1": "Custom Field 1",
    "custom2": "Custom Field 2",
    "custom3": "Custom Field 3",
    "custom4": "Custom Field 4",
    "custom5": "Custom Field 5",
  }
}

 

Note that the userName attribute refers to the SSO login ID. The ExternalID attribute is available for external references.

Note also that the userType refers to the name of the profile for the user.

Fetch users by ID

Users can be fetched by the SCIM User.id attribute:

GET /scim/v2/org_id/Users/user1
Authorization: Bearer <token>

 

And an example response follows:

HTTP/1.1 200 OK
Content-Length: 493
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT
Location: https://api.outreach.io/scim/scim/v2/org_id/Users/user1

 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
  ],
  "id": "user1",
  "externalId": "external_id1",
  "meta": {
    "resourceType": "User",
    "created": "2020-08-18T14:21:46.57681-07:00",
    "lastModified": "2020-08-18T14:21:46.57681-07:00",
    "location": "https://api.outreach.io/scim/scim/v2/org_id/Users/user1"
  },
  "userName": "user@sso.credentials",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "displayName": "John Doe",
  "emails": [
    {
      "value": "user@sso.credentials",
      "primary": true,
    }
  ]
  "active": true,
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
    "profileName": "Outreach SDR Profile",
    "roleName": "Sales OPS",
    "custom1": "Custom Field 1",
    "custom2": "Custom Field 2",
    "custom3": "Custom Field 3",
    "custom4": "Custom Field 4",
    "custom5": "Custom Field 5",
  }
}

 

Fetch users by UserName

Users can also be fetched by UserName (which is required to match the email used for SSO login). This is done via a SCIM filter which will yield a single result.

GET /scim/v2/org_id/Users?filter=userName%20eq%20”user%40sso.credentials”
Authorization: Bearer <token>

And an example response follows:

HTTP/1.1 200 OK
Content-Length: 696
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
      ],
      "id": "user1",
      "externalId": "external_id1",
      "meta": {
        "resourceType": "User",
        "created": "2020-08-18T14:21:46.57681-07:00",
        "lastModified": "2020-08-18T14:21:46.57681-07:00",
        "location": "https://api.outreach.io/scim/scim/v2/org_id/Users/user1"
      },
      "userName": "user@sso.credentials",
      "name": {
        "familyName": "Doe",
        "givenName": "John"
      },
      "displayName": "John Doe",
      "emails": [
        {
          "value": "user@sso.credentials",
          "primary": true,
        }
      ]
      "active": true,
      "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
        "profileName": "Outreach SDR Profile",
        "roleName": "Sales OPS",
        "custom1": "Custom Field 1",
        "custom2": "Custom Field 2",
        "custom3": "Custom Field 3",
        "custom4": "Custom Field 4",
        "custom5": "Custom Field 5",
      }
    }
  ]
}

 

Fetch users by ExternalID

As with a UserName filter, Users can also be filtered for matching ExternalID.

GET /scim/v2/org_id/Users?filter=externalId%20eq%20”external_id1”
Authorization: Bearer <token>

 

And an example response follows:

HTTP/1.1 200 OK
Content-Length: 696
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
      ],
      "id": "user1",
      "externalId": "external_id1",
      "meta": {
        "resourceType": "User",
        "created": "2020-08-18T14:21:46.57681-07:00",
        "lastModified": "2020-08-18T14:21:46.57681-07:00",
        "location": "https://api.outreach.io/scim/scim/v2/org_id/Users/user1"
      },
      "userName": "user@sso.credentials",
      "name": {
        "familyName": "Doe",
        "givenName": "John"
      },
      "displayName": "John Doe",
      "emails": [
        {
          "value": "user@sso.credentials",
          "primary": true,
        }
      ]
      "active": true,
      "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
        "profileName": "Outreach SDR Profile",
        "roleName": "Sales OPS",
        "custom1": "Custom Field 1",
        "custom2": "Custom Field 2",
        "custom3": "Custom Field 3",
        "custom4": "Custom Field 4",
        "custom5": "Custom Field 5",
      }
    }
  ]
}

 

No other user filters

The Users object does not support any other filters defined by SCIM, both in terms of operators/expressions as well as in terms of attributes.

Updating users

Users can be updated by using PUT to update all the fields. Note that fields that are set to null or not set at all may be cleared.  We clear custom fields on PUT requests.

Due to the above, we recommend using PATCH to update users instead of PUT as PATCH allows updating just the fields needed.

For example, the "John Doe" user created before can be made inactive as follows:

PUT /scim/v2/org_id/Users/user1
Authorization: Bearer <token>

 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
  ],
  "externalId": "external_id1",
  "meta": {
    "created": "0001-01-01T00:00:00Z",
    "lastModified": "0001-01-01T00:00:00Z"
  },
  "userName": "user@sso.credentials",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "active": false,
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
    "profileName": "Outreach SDR Profile",
    "roleName": "Sales OPS",
    "custom1": "Custom Field 1",
    "custom2": "Custom Field 2",
    "custom3": "Custom Field 3",
    "custom4": "Custom Field 4",
    "custom5": "Custom Field 5",
  }
}

And an example response follows:

HTTP/1.1 200 OK

Content-Length: 495
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
  ],
  "id": "user1",
  "externalId": "external_id1",
  "meta": {
    "resourceType": "User",
    "created": "2020-08-18T14:21:46.57681-07:00",
    "lastModified": "2020-08-18T14:21:46.577919-07:00",
    "location": "https://api.outreach.io/scim/scim/v2/org_id/Users/user1"
  },
  "userName": "user@sso.credentials",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "displayName": "John Doe",
  "emails": [
    {
      "value": "user@sso.credentials",
      "primary": true,
    }
  ]
  "active": false,
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
    "profileName": "Outreach SDR Profile",
    "roleName": "Sales OPS",
    "custom1": "Custom Field 1",
    "custom2": "Custom Field 2",
    "custom3": "Custom Field 3",
    "custom4": "Custom Field 4",
    "custom5": "Custom Field 5",
  }
}

 

The following is a PUT to update a custom field (missing custom3 and custom5 set to null).  Note that missing or null custom fields are treated as the empty string (and will clear out existing values).

Authorization: Bearer <token>

 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
  ],
  "externalId": "external_id1",
  "meta": {
    "created": "0001-01-01T00:00:00Z",
    "lastModified": "0001-01-01T00:00:00Z"
  },
  "userName": "user@sso.credentials",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "active": false,
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
    "profileName": "Outreach SDR Profile",
    "roleName": "Sales OPS",
    "custom1": "New Custom Field 1",
    "custom2": "New Custom Field 2",
    "custom4": "New Custom Field 4",
    "custom5": null,
  }
}

 

And an example response follows, note that custom3 and custom5 have been set to the empty string:

HTTP/1.1 200 OK

Content-Length: 495
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
  ],
  "id": "user1",
  "externalId": "external_id1",
  "meta": {
    "resourceType": "User",
    "created": "2020-08-18T14:21:46.57681-07:00",
    "lastModified": "2020-08-18T14:21:46.577919-07:00",
    "location": "https://api.outreach.io/scim/scim/v2/org_id/Users/user1"
  },
  "userName": "user@sso.credentials",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "displayName": "John Doe",
  "emails": [
    {
      "value": "user@sso.credentials",
      "primary": true,
    }
  ]
  "active": false,
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
    "profileName": "Outreach SDR Profile",
    "roleName": "Sales OPS",
    "custom1": "New Custom Field 1",
    "custom2": "New Custom Field 2",
    "custom3": "",
    "custom4": "New Custom Field 4",
    "custom5": "",
  }
}

 

Updating users with PATCH

Specific fields of a user can be modified using PATCH. For example, the "John Doe" user created before can be made inactive as follows:

PATCH /scim/v2/org_id/Users/user1
Authorization: Bearer <token>

 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  “Operations”: [{
    “op”: “replace”,
    "value": {
      "active": false
    }
  ]]
}

 

And an example response follows:

HTTP/1.1 200 OK
Content-Length: 495
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:outreach:2.0:User"
  ],
  "id": "user1",
  "externalId": "external_id1",
  "meta": {
    "resourceType": "User",
    "created": "2020-08-18T14:21:46.57681-07:00",
    "lastModified": "2020-08-18T14:21:46.577919-07:00",
    "location": "https://api.outreach.io/scim/scim/v2/org_id/Users/user1"
  },
  "userName": "user@sso.credentials",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "userType": "Outreach SDR Profile",
  "active": false,
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:User": {
    "profileName": "Outreach SDR Profile",
    "roleName": "Sales OPS",
    "custom1": "Custom Field 1",
    "custom2": "Custom Field 2",
    "custom3": "Custom Field 3",
    "custom4": "Custom Field 4",
    "custom5": "Custom Field 5",
  }
}

At this time Outreach only supports the "replace" operation for Users and only supports paths that are simple attribute names. No complex filters ar supported. Extended attributes can be accessed via the urn. For instance, the profileName can be accessed via:

urn:ietf:params:scim:schemas:extension:outreach:2.0:User:profileName

as the patch value in the patch operation.

Deleting users

Outreach does not support deleting users.  Outreach recommends setting active to false for the user instead. Setting the active property of a user to false would ensure that the user is not counted against the licensed seats.

Groups

ƒ The Extended Group attributes are available in the

urn:ietf:params:scim:schemas:extension:outreach:2.0:Group

object on the group resource.
There is currently only one type of "groups" supported by the Outreach SCIM implementation, "Outreach Team."

Outreach Teams

The teams constructed by Outreach are specified in SCIM by the "Outreach Team" value in the Extended Group type attribute. When the value of "OutreachTeam" is specified in requests SCIM will attempt to create, modify, or retrieve data for existing Outreach Teams.

List Groups

Groups can also be enumerated by a direct GET to the /Groups endpoint:

GET /scim/v2/org_id/Groups
Authorization: Bearer <token>

 

And an example response follows:

HTTP/1.1 200 OK
Content-Length: 541
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
      ],
      "id": "
{{group3}}",
      "externalId": "external_gid2",
      "urn:ietf:params:scim:schemas:extension:outreach:2.0:Group": {
        "color": "#a4bdfc",
        "type": "OutreachTeam"
      },
      "meta": {
        "resourceType": "Group",
        "created": "2020-08-18T14:21:46.578657-07:00",
        "lastModified": "0001-01-01T00:00:00Z",
        "location": "https://api.outreach.io/scim/scim/v2/org_id/Groups/group3"
      },
      "displayName": "My group #2"
    }
  ]
}

Create Groups:

Groups can be created via a POST to the /Groups endpoint:

POST /scim/v2/org_id/Groups
Authorization: Bearer <token>
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "externalId": "external_gid1",
  "displayName": "My group #1",

  "members": [
    {
      "value": "{{user1}}",
      "type": "User"
    }
  ]
}

And an example response follows:

HTTP/1.1 201 Created
Content-Length: 439
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT
Location: https://api.outreach.io/scim/scim/v2/org_id/Groups/group2

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension-outreach:2.0:Group"
  ],
  "id": "{{group2}}",
  "externalId": "external_gid1",
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:Group": {
    “Color”: “#a4bdfc”,
    "type": "OutreachTeam",
  },
  "meta": {
    "resourceType": "Group",
    "created": "2020-08-18T14:21:46.578287-07:00",
    "lastModified": "0001-01-01T00:00:00Z",
    "location": "https://api.outreach.io/scim/scim/v2/org_id/Groups/group2"
  },
  "displayName": "My group #1",
  "members": [
    {
      "value": "{{user1}}",
      "type": "User"
    }
  ]
}

Delete Groups

Unlike Users, Groups can be deleted via a DELETE:

DELETE /scim/v2/org_id/Groups/group2
Authorization: Bearer <token>

And an example response follows:

HTTP/1.1 204 No Content
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

 

Fetch Groups by ID

Groups can be fetched by the group ID:

GET /scim/v2/org_id/Groups/group3
Authorization: Bearer <token>

And an example response follows:

HTTP/1.1 200 OK

Content-Length: 362
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "{{group3}}",
  "externalId": "external_gid2",
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:Group": {
    “Color”: “#a4bdfc”,
    "type": "OutreachTeam"
  },
  "meta": {
    "resourceType": "Group",
    "created": "2020-08-18T14:21:46.578657-07:00",
    "lastModified": "0001-01-01T00:00:00Z",
    "location": "https://api.outreach.io/scim/scim/v2/org_id/Groups/group3"
  },
  "displayName": "My group #2"
}

Note that because the groupType filter was not specified in teh request URL this defaulted to returning an "OutreachTeam" resource.

Fetch Group by ExternalID

Groups can also be fetched by externalID:

GET /scim/v2/org_id/Groups?filter=externalId%20eq%20”external_gid2”
Authorization: Bearer <token>

And an example response follows:

HTTP/1.1 200 OK

Content-Length: 541
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "{{group3}}",
      "externalId": "external_gid2",
      "urn:ietf:params:scim:schemas:extension:outreach:2.0:Group": {
	  “Color”: “#a4bdfc”,
        "type": "OutreachTeam"
      },
      "meta": {
        "resourceType": "Group",
        "created": "2020-08-18T14:21:46.578657-07:00",
        "lastModified": "0001-01-01T00:00:00Z",
        "location": "https://api.outreach.io/scim/scim/v2/org_id/Groups/group3"
      },
      "displayName": "My group #2"
    }
  ]
}

Note that because the groupType filter was not specified this defaulted to returning an "OutreachTeam" resource.

Updating Groups

Group membership can be updated using PATCH. The following adds John Doe to the last group:

 

PATCH /scim/v2/org_id/Groups/groups3
Authorization: Bearer <token>
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  “Operations”: [{
    “op”: “add”,
    “path”: “members”,
    "value": [{
      "value": "{{user1}}",
      "type": "User”, 
    }]
  ]]
}

Note: For the patch operation the type for the member is optional.

And an example response follows:

HTTP/1.1 200 OK
Content-Length: 362
Content-Type: application/scim+json; charset=utf8
Date: Tue, 18 Aug 2020 21:21:46 GMT

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "{{group3}}",
  "externalId": "external_gid2",
  "urn:ietf:params:scim:schemas:extension:outreach:2.0:Group": {
    “Color”: “#a4bdfc”,
    "type": "OutreachTeam"  },
  "meta": {
    "resourceType": "Group",
    "created": "2020-08-18T14:21:46.578657-07:00",
    "lastModified": "0001-01-01T00:00:00Z",
    "location": "https://api.outreach.io/scim/scim/v2/org_id/Groups/group3"
  },
  "displayName": "My group #2”,
  “members”: [
    {
      "value": "{{user1}}",
      "type": "User"
    }
  ]
}

The “groupId” values are globally unique so specifying the resource type is not required, the SCIM implementation will find the appropriate group, regardless of type, and update it. As with the Users endpoint, only a limited set of operations are permitted with PATCH. In particular, direct elements are allowed to be updated and group-adds are permitted as above. Deleting specific members in the group can use the simple path expression

 members[value eq "<id>"]

Related articles