The System for Cross-domain Identity Management (SCIM) specification simplifies managing user identities in cloud-based applications. SCIM aims to reduce the cost and complexity of user management by providing a common user schema and standard protocols for exchanging this information.
Enterprise clients who maintain their own Single Sign-On to manage (register, activate, deactivate, change email address) users within their domain on Upwork platform can use SCIM to automate user management.
Access credentials
-
URL:
https://www.upwork.com/api/v3/scim/v2/{tenantId}/ - Tenant ID is provided by Upwork (scim-tenant-id is used for examples below)
- Bearer access token is provided by Upwork (scim-access-token is used for examples below)
User attributes
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "johnsmith",
"externalId": "3ad36cf6-04c1-4eed-9440-0a86cb612ffd",
"active": true,
"emails": [{"type": "work", "value": "johnsmith@domain.com"}],
"name": {"givenName": "John", "familyName": "Smith"},
"addresses": [{"type": "work", "country": "US"}],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "IT"
}
}
Mandatory attributes
- Email address: At least one work email address must be specified. In the case of multiple addresses, the primary attribute must be set to true for the primary email address.
- Given (first) name
- Family (last) name
- Country code: There must be at least one work address defined with ISO-3166 Alpha-2 country code.
Important to know
- We do not recommend storing optional user data unless necessary. We support a limited number of SCIM attributes; all unsupported attributes are ignored
- Updates are only supported for activation, deactivation and email change. Any other attribute updates will not affect the user profiles
Request examples
Create user
Request
Javascript
POST https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users
Authorization: Bearer {scim-access-token}
Content-Type: application/scim+json
Accept: application/scim+json
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "johnsmith",
"emails": [{"type": "work", "value": "johnsmith@domain.com"}],
"name": {"givenName": "John", "familyName": "Smith"},
"addresses": [{"type": "work", "country": "US"}],
"active": true
}
Response
Javascript
201 Created
Content-Type: application/scim+json
ETag: W/"96b065a4"
Location: https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
"userName": "johnsmith",
"meta": {
"resourceType": "User",
"created": "2020-09-23T21:18:11.463Z",
"lastModified": "2020-09-23T21:18:11.463Z"
},
"active": true,
"addresses": [{"type": "work", "country": "US"}],
"emails": [{"type": "work", "value": "johnsmith@domain.com"}],
"name": {"givenName": "John", "familyName": "Smith"}
}
Get user
Request
Javascript
GET https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1
Authorization: Bearer {scim-access-token}
Accept: application/scim+json
Response
Javascript
200 OK
Content-Type: application/scim+json
ETag: W/"96b065a4"
Location: https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
"userName": "johnsmith",
"meta": {
"resourceType": "User",
"created": "2020-09-23T21:18:11.463Z",
"lastModified": "2020-09-23T21:18:11.463Z"
},
"active": true,
"addresses": [{"type": "work", "country": "US"}],
"emails": [{"type": "work", "value": "johnsmith@domain.com"}],
"name": {"givenName": "John", "familyName": "Smith"}
}
Query users
Request
Javascript
GET https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users?filter=id%20eq%20%224ee540f5-1f69-4e3d-86fb-b32ae79316f1%22&startIndex=1&count=10
Authorization: Bearer {scim-access-token}
Accept: application/scim+json
Response
Javascript
200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 10,
"Resources": [
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
"userName": "johnsmith",
"meta": {
"resourceType": "User",
"created": "2020-09-23T21:18:11.463Z",
"lastModified": "2020-09-23T21:18:11.463Z",
"location": "https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
"version": "W/\"96b065a4\""
},
"active": true,
"addresses": [{"type": "work", "country": "US"}],
"emails": [{"type": "work", "value": "johnsmith@domain.com"}],
"name": {"givenName": "John", "familyName": "Smith"}
}
]
}
Note:
User querying is only supported for a limited number of attributes (id, username, externalId) and conditions (eq, and). Order is not supported.
Patch user (deactivation example)
Request
Javascript
PATCH https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1
Authorization: Bearer {scim-access-token}
Content-Type: application/scim+json
Accept: application/scim+json
If-Match: W/"96b065a4"
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"operations": [{"op": "replace", "path": "active", "value": false}]
}
Response
Javascript
200 OK
Content-Type: application/scim+json
ETag: W/"66ff0656"
Location: https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
"userName": "johnsmith",
"meta": {
"resourceType": "User",
"created": "2020-09-23T21:18:11.463Z",
"lastModified": "2020-09-23T22:08:45.559Z"
},
"active": false,
"addresses": [{"type": "work", "country": "US"}],
"emails": [{"type": "work", "value": "johnsmith@domain.com"}],
"name": {"givenName": "John", "familyName": "Smith"}
}
Note:
Filters are not supported for add operation in PATCH requests.
This will not work:
{
"op": "add",
"path": "addresses[type eq \"other\"].streetAddress",
"value": "221B Baker St."
}
Composite objects should be added like this:
{
"op": "add",
"path": "addresses",
"value": [{"type": "other", "streetAddress": "221B Baker St."}]
}
Replace user (email address change example)
Request
Javascript
PUT https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1
Authorization: Bearer {scim-access-token}
Content-Type: application/scim+json
Accept: application/scim+json
If-Match: W/"66ff0656"
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
"userName": "johnsmith",
"active": false,
"addresses": [{"type": "work", "country": "US"}],
"emails": [{"type": "work", "value": "johnsmith-updated@domain.com"}],
"name": {"givenName": "John", "familyName": "Smith"}
}
Response
Javascript
200 OK
Content-Type: application/scim+json
ETag: W/"a7b462b8"
Location: https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
"userName": "johnsmith",
"meta": {
"resourceType": "User",
"created": "2020-09-23T21:18:11.463Z",
"lastModified": "2020-09-23T22:27:18.114Z"
},
"active": false,
"addresses": [{"type": "work", "country": "US"}],
"emails": [{"type": "work", "value": "johnsmith-updated@domain.com"}],
"name": {"givenName": "John", "familyName": "Smith"}
}
Delete user
Request
Javascript
DELETE https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1
Authorization: Bearer {scim-access-token}
Response
Javascript
204 No content
Note:
This request deactivates the user account, but does not remove the user from the Upwork platform.
Known limitations
- Groups are not supported
- Bulk updates are not supported
- Discovery endpoints are not supported