Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BD-3655: Updates to SCIM endpoint docs #8448

Merged
merged 5 commits into from
Nov 26, 2024
Merged

BD-3655: Updates to SCIM endpoint docs #8448

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d3c5247
bd-3655 update scim docs pt 1 edits
lydia-xie Nov 19, 2024
fecc2ce
edits
lydia-xie Nov 20, 2024
affd1ca
BD-3708
lydia-xie Nov 26, 2024
c7c9170
bd-3706
lydia-xie Nov 26, 2024
241d041
fix
lydia-xie Nov 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _docs/_api/endpoints/scim/delete_existing_dashboard_user.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ This is similar to deleting a user in the **Company Users** section of the Braze

## Prerequisites

To use this endpoint, you'll need a SCIM token. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).
To use this endpoint, you'll need a SCIM token. You'll use your service origin as the `X-Request-Origin` header. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).

## Rate limit

Expand Down
2 changes: 1 addition & 1 deletion _docs/_api/endpoints/scim/get_search_existing_dashboard_user.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Note that when the query parameter is URL encoded it will read like this:

## Prerequisites

To use this endpoint, you'll need a SCIM token. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).
To use this endpoint, you'll need a SCIM token. You'll use your service origin as the `X-Request-Origin` header. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).

## Rate limit

Expand Down
23 changes: 21 additions & 2 deletions _docs/_api/endpoints/scim/get_see_user_account_information.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ description: "This article outlines details about the Look up an existing dashbo

## Prerequisites

To use this endpoint, you'll need a SCIM token. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).
To use this endpoint, you'll need a SCIM token. You'll use your service origin as the `X-Request-Origin` header. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).

## Rate limit

Expand All @@ -31,7 +31,7 @@ To use this endpoint, you'll need a SCIM token. For more information, refer to [

| Parameter | Required | Data Type | Description |
|---|---|---|---|
| `id` | Required | String | The user's resource ID. This parameter is returned by the `POST` `/scim/v2/Users/` or `GET` `/scim/v2/Users?filter=userName eq "user@test.com"` methods. |
| `id` | Required | String | The user's resource ID. This parameter is returned by the `POST` `/scim/v2/Users/` or `GET` `/scim/v2/Users?filter=userName eq "user@test.com"` methods. |
{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4 role="presentation" }

## Request body
Expand Down Expand Up @@ -63,6 +63,25 @@ curl --location --request GET 'https://rest.iad-01.braze.com/scim/v2/Users/dfa24
"lastSignInAt": "Thursday, January 1, 1970 12:00:00 AM",
"permissions": {
"companyPermissions": ["manage_company_settings"],
"roles": [
{
"roleName": "Another Test Role",
"roleId": "23125dad23dfaae7,
"appGroup": [
{
"appGroupId": "241adcd25adfabcded",
"appGroupName": "Production Workspace",
"appGroupPermissionSets": [
{
"appGroupPermissionSetName": "A Permission Set",
"appGroupPermissionSetId": "dfa385109bc38",
"permissions": ["basic_access","publish_cards"]
}
]
}
]
}
],
"appGroup": [
{
"appGroupId": "241adcd25789fabcded",
Expand Down
83 changes: 72 additions & 11 deletions _docs/_api/endpoints/scim/post_create_user_account.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ description: "This article outlines details about the Create new dashboard user

## Prerequisites

To use this endpoint, you'll need a SCIM token. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).
To use this endpoint, you'll need a SCIM token. You'll use your service origin as the `X-Request-Origin` header. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).

## Rate limit

Expand All @@ -32,7 +32,7 @@ To use this endpoint, you'll need a SCIM token. For more information, refer to [
```
Content-Type: application/json
X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE
Authorization: Bearer YOUR-REST-API-KEY
Authorization: Bearer YOUR-SCIM-TOKEN-KEY
```
```
{
Expand All @@ -45,6 +45,14 @@ Authorization: Bearer YOUR-REST-API-KEY
"department": "finance",
"permissions": {
"companyPermissions": ["manage_company_settings"],
"roles": [
{
"roleName": "Test Role"
},
{
"roleId": "2519dafcdba238ae7"
}
],
"appGroup": [
{
"appGroupName": "Test Workspace",
Expand Down Expand Up @@ -73,19 +81,19 @@ Authorization: Bearer YOUR-REST-API-KEY

| Parameter | Required | Data type | Description |
| --------- | -------- | --------- | ----------- |
| `schemas` | Required | Array of strings | Expected SCIM 2.0 schema name for user object. |
| `schemas` | Required | Array of strings | Expected SCIM 2.0 schema name for the user object. |
| `userName` | Required | String | The user's email address. |
| `name` | Required | JSON object | This object contains the user's given name and family name. |
| `department` | Required | String | Valid department string from the [department string documentation]({{site.baseurl}}/scim_api_appendix/#department-strings). |
| `permissions` | Required | JSON object | Permissions object as described in the [permissions object documentation]({{site.baseurl}}/scim_api_appendix/#permissions-object). |
| `permissions` | Optional | JSON object | Permissions object as described in the [permissions object documentation]({{site.baseurl}}/scim_api_appendix/#permissions-object). |
{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4 role="presentation" }

## Example request
```json
curl --location --request POST 'https://rest.iad-01.braze.com/scim/v2/Users' \
--header 'Content-Type: application/json' \
--header 'X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--header 'Authorization: Bearer YOUR-SCIM–TOKEN-HERE' \
--data raw '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "user@test.com",
Expand All @@ -96,6 +104,14 @@ curl --location --request POST 'https://rest.iad-01.braze.com/scim/v2/Users' \
"department": "finance",
"permissions": {
"companyPermissions": ["manage_company_settings"],
"roles": [
{
"roleName": "Test Role"
},
{
"roleId": "2519dafcdba238ae7"
}
],
"appGroup": [
{
"appGroupName": "Test Workspace",
Expand All @@ -106,10 +122,10 @@ curl --location --request POST 'https://rest.iad-01.braze.com/scim/v2/Users' \
"teamPermissions": ["basic_access","export_user_data"]
}
]
}
}
]
}
}
}'
```

## Response
Expand All @@ -126,6 +142,43 @@ curl --location --request POST 'https://rest.iad-01.braze.com/scim/v2/Users' \
"lastSignInAt": "Thursday, January 1, 1970 12:00:00 AM",
"permissions": {
"companyPermissions": ["manage_company_settings"],
"roles": [
{
"roleName": "Test Role",
"roleId": "519dafcdba23dfaae7,
"appGroup": [
{
"appGroupId": "241adcd25789fabcded",
"appGroupName": "Some Workspace",
"appGroupPermissions": ["basic_access", "publish_cards"],
"team": [
{
"teamId": "2519dafcdba238ae7",
"teamName": "Some Team",
"teamPermissions": ["export_user_data"]
}
]
}
]
},
{
"roleName": "Another Test Role",
"roleId": "23125dad23dfaae7,
"appGroup": [
{
"appGroupId": "241adcd25adfabcded",
"appGroupName": "Production Workspace",
"appGroupPermissionSets": [
{
"appGroupPermissionSetName": "A Permission Set",
"appGroupPermissionSetId": "dfa385109bc38",
"permissions": ["basic_access","publish_cards"]
}
]
}
]
}
],
"appGroup": [
{
"appGroupId": "241adcd25789fabcded",
Expand All @@ -138,7 +191,15 @@ curl --location --request POST 'https://rest.iad-01.braze.com/scim/v2/Users' \
"teamPermissions": ["basic_access","export_user_data"]
}
]
}
},
{
"appGroupName": "Other Test Workspace",
"appGroupPermissionSets": [
{
"appGroupPermissionSetName": "Test Permission Set"
}
]
}
]
}
}
Expand All @@ -148,9 +209,9 @@ curl --location --request POST 'https://rest.iad-01.braze.com/scim/v2/Users' \

| Parameter | Data type | Description |
| --------- | --------- | ----------- |
| `schemas` | Array of strings | Expected SCIM 2.0 schema name for user object. |
| `schemas` | Array of strings | Expected SCIM 2.0 schema name for the user object. |
| `userName` | String | The user's email address. |
| `name` | JSON object | This object contains the user's given name and family name. |
| `name` | JSON object | This object contains the user's first name and family name. |
| `department` | String | Valid department string from the [department string documentation]({{site.baseurl}}/scim_api_appendix/#department-strings). |
| `permissions` | JSON object | Permissions object as described in the [permissions object documentation]({{site.baseurl}}/scim_api_appendix/#permissions-object). |
| `id` | String | ID generated by Braze that is used for searching and managing user accounts. |
Expand All @@ -159,7 +220,7 @@ curl --location --request POST 'https://rest.iad-01.braze.com/scim/v2/Users' \

### Error states

If a user with this email address already exists in Braze, the endpoint will respond with:
If a user with this `userName` or email address already exists in Braze, the endpoint will respond with:

```json
HTTP/1.1 409 Conflict
Expand Down
67 changes: 60 additions & 7 deletions _docs/_api/endpoints/scim/put_update_existing_user_account.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ For security reasons, `userName` (email address) cannot be updated through this

## Prerequisites

To use this endpoint, you'll need a SCIM token. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).
To use this endpoint, you'll need a SCIM token. You'll use your service origin as the `X-Request-Origin` header. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning/).

## Rate limit

Expand All @@ -42,7 +42,7 @@ To use this endpoint, you'll need a SCIM token. For more information, refer to [
```
Content-Type: application/json
X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE
Authorization: Bearer YOUR-REST-API-KEY
Authorization: Bearer YOUR-SCIM-TOKEN-KEY
```
```json
{
Expand All @@ -54,6 +54,14 @@ Authorization: Bearer YOUR-REST-API-KEY
"department": "finance",
"permissions": {
"companyPermissions": ["manage_company_settings"],
"roles": [
{
"roleName": "Test Role"
},
{
"roleId": "2519dafcdba238ae7"
}
],
"appGroup": [
{
"appGroupName": "Test Workspace",
Expand All @@ -62,7 +70,7 @@ Authorization: Bearer YOUR-REST-API-KEY
{
"teamName": "Test Team",
"teamPermissions": ["admin"]
}
}
]
},
{
Expand All @@ -72,7 +80,7 @@ Authorization: Bearer YOUR-REST-API-KEY
"appGroupPermissionSetName": "Test Permission Set"
}
]
}
}
]
}
}
Expand All @@ -94,7 +102,7 @@ Authorization: Bearer YOUR-REST-API-KEY
curl --location --request PUT 'https://rest.iad-01.braze.com/scim/v2/Users/dfa245b7-24195aec-887bb3ad-602b3340' \
--header 'Content-Type: application/json' \
--header 'X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--header 'Authorization: Bearer YOUR-SCIM-TOKEN-HERE' \
--data raw '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"name": {
Expand All @@ -104,6 +112,14 @@ curl --location --request PUT 'https://rest.iad-01.braze.com/scim/v2/Users/dfa24
"department": "finance",
"permissions": {
"companyPermissions": ["manage_company_settings"],
"roles": [
{
"roleName": "Test Role"
},
{
"roleId": "2519dafcdba238ae7"
}
],
"appGroup": [
{
"appGroupName": "Test Workspace",
Expand All @@ -114,7 +130,7 @@ curl --location --request PUT 'https://rest.iad-01.braze.com/scim/v2/Users/dfa24
"teamPermissions": ["admin"]
}
]
}
}
]
}
}
Expand All @@ -134,6 +150,43 @@ curl --location --request PUT 'https://rest.iad-01.braze.com/scim/v2/Users/dfa24
"lastSignInAt": "Thursday, January 1, 1970 12:00:00 AM",
"permissions": {
"companyPermissions": ["manage_company_settings"],
"roles": [
{
"roleName": "Test Role",
"roleId": "519dafcdba23dfaae7,
"appGroup": [
{
"appGroupId": "241adcd25789fabcded",
"appGroupName": "Some Workspace",
"appGroupPermissions": ["basic_access", "publish_cards"],
"team": [
{
"teamId": "2519dafcdba238ae7",
"teamName": "Some Team",
"teamPermissions": ["export_user_data"]
}
]
}
]
},
{
"roleName": "Another Test Role",
"roleId": "23125dad23dfaae7,
"appGroup": [
{
"appGroupId": "241adcd25adfabcded",
"appGroupName": "Production Workspace",
"appGroupPermissionSets": [
{
"appGroupPermissionSetName": "A Permission Set",
"appGroupPermissionSetId": "dfa385109bc38",
"permissions": ["basic_access","publish_cards"]
}
]
}
]
}
],
"appGroup": [
{
"appGroupId": "241adcd25789fabcded",
Expand All @@ -146,7 +199,7 @@ curl --location --request PUT 'https://rest.iad-01.braze.com/scim/v2/Users/dfa24
"teamPermissions": ["admin"]
}
]
}
}
]
}
}
Expand Down
11 changes: 11 additions & 0 deletions _docs/_hidden/misc_reference/scim_api_appendix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ A valid permissions object is a JSON object with the following key-value pairs:
| Key | Required | Data type | Description |
| --- | --- | --- | --- |
| `companyPermissions` | Optional | Array | Array of company-level permission strings from the [Company permission strings](#company) table, in which the presence of the string corresponds to the user having the corresponding permission. |
| `roles` | Optional | Array | Array of [role objects](#role-object). |
| `appGroup` | Required | Array | Array of [workspace permission objects](#workspace-permission-object). |
{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4 role="presentation" }

Expand Down Expand Up @@ -69,6 +70,16 @@ A valid team permission object is a JSON object with the following key-value pai
| `teamPermissions` | Required | Array | Array of team-level permission strings from the [teams permission strings](#team) table, in which the presence of the string corresponds to the user having the corresponding permission for the specified team. |
{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4 role="presentation" }

## Role object

A valid role object is a JSON object with the following key value pairs:

| Key | Required | Data type | Description |
| --- | --- | --- | --- |
| `roleName` | Optional | String | Name of the role that is being assigned to the user. |
| `roleId` | Required if `roleName` is missing | String | ID of the role, serving as an alternative method of specifying the role. |
{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4 role="presentation" }

## Appendix

### Company permission strings {#company}
Expand Down