✓ SCIM User Management via API

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

In this article

Articles in this section

Was this article helpful?

0 out of 0 found this helpful
{"global":{"message":"","icon":"info","start":"","end":""},"responsive":[{"message":"","country":"All","usertype":"all","icon":"info","start":"","end":""},{"message":"","country":"All","usertype":"all","icon":"info","start":"","end":""}]}