✓ SCIM User Management via API

0113f8 d76c48
Have more questions? Submit a request

SCIM enables enterprise clients to automate user management on Upwork through a standardized API using tenant-specific credentials. It supports user creation, deactivation, email updates, and limited attribute queries. Required fields include name, email, and country. Group management, bulk updates, and most user attribute changes beyond activation or email edits are not supported.

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

Articles in this section

See more
Was this article helpful?
0 out of 0 found this helpful
Share

Comments

0 comments

Please sign in to leave a comment.