Skip to main content
All CollectionsMarketplace integrationsCore HR & payroll
SCIM
SCIM
Updated yesterday

⚠️ If you’re already using Javelo and have users in the app, please read Preparing Javelo for External User Source Integration before proceeding.

Introduction

The SCIM protocol is an application-level REST protocol for provisioning and managing identity data on the web. The protocol supports creation, discovery, retrieval, and modification of core identity resources.

You can find more information on the core concepts of the SCIM protocol here.

Authorization

In order to be able to do any operation (creating or updating users), using SCIM endpoints, you need to use the authentication token issued during SCIM integration activation.

The authentication is done through request headers, for example:

{
  "headers": {
    "authorization": "Bearer <token>",
    "Content-Type": "application/scim+json"
  }
}

⚠️ Your Javelo account needs some high privileges to achieve this step.

  1. Go to “Settings" (⚙️ icon) in the upper right corner of your Javelo account

  2. Select “Integrations” from the navigation menu under the Company section

  3. Click on "Configuration" in SCIM integration panel

  4. Click on "Activate scim"

    This action will generate a token. Copy the token and paste it in your SCIM interface to start the synchronization.

    ❗ Please note that the token is only displayed once. If you fail to store it, you will need to generate a new one through this integration configuration modal.

API Prefix

There are two possible prefixes to use with all endpoints depending on the purpose, whether it is for testing or to use in production:

In further Docs we will refer to it as JAVELO-API:

If you want access to an environment for testing please get in touch with our support team.

GET - List

Retrieve all users

GET /scim/v2/Users HTTP/1.1
Authorization: <Authorization credentials>

To paginate use start_index and count params, for example:

GET /scim/v2/Users?start_index=1&count=3 HTTP/1.1
Authorization: <Authorization credentials>

Then you can retrieve the pagination fields from the response:

 {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 12,
    "startIndex": 1,
    "itemsPerPage": 3,
    "Resources": [...]
}

Get - Search

You may use the same endpoint you will use for listing user to search some users with a search expression:

GET /scim/v2/Users?filter=userName+eq+email%40test.org HTTP/1.1
Authorization: <Authorization credentials>

Then you will get a list of users that match the expression:

 {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 20,
    "Resources": [...]
}

Note that only a part of the RFC specification is currently implemented, and only some attributes are searchable.

The specification state that filtering support is optional and define a lot of operators. We only support one for the moment : eq.

The list of supported attributes is:

  • userName

  • givenName (will apply the filter on the name.givenName value)

  • familyName (will apply the filter on the name.familyName value)

  • displayName

  • email

  • externalId

Please note that the value of the filter in query parameter has to be URL-encoded.

Get - Retrieve one user

Retrieve a user using user id:

GET /scim/v2/Users/94fe546f-66e1-4818-88f4-399da170b453 HTTP/1.1
Authorization: <Authorization credentials>

The response will look like this:

{
  "schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:javelo:2.0:User"
	],
  "id": "94fe546f-66e1-4818-88f4-399da170b453",
  "userName": "[email protected]",
  "externalId": "aaeojd012",
  "name": { "givenName": "Bill", "familyName": "Wallace" },
  "emails": [{ "primary": true, "value": "[email protected]" }],
  "displayName": "Bill Wallace",
  "locale": "en-US",
  "active": true,
  "title": "Engineer",
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+18045001160"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Research and Developement",
		"employeeNumber": "AEFM34IX",
		"organization": "MyCompany SAS"
  },
	"urn:ietf:params:scim:schemas:extension:javelo:2.0:User": {
    "managerUserName": "[email protected]",
    "status": "Executive",
    "seniorityDate": "2008-01-23T04:56:22Z",
    "contractStartDate": "2000-03-15T04:56:22Z"
  }
}

POST - Create

To create a user make a POST request to the endpoint <JAVELO-API>/scim/v2/Users with the following payload:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "externalId": "aaeojd012",
  "name": { "givenName": "Bill", "familyName": "Wallace" },
  "emails": [{ "primary": true, "value": "[email protected]" }],
  "displayName": "Bill Wallace",
  "locale": "en-US",
  "active": true,
  "title": "Engineer",
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+18045001160"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Research and Developement",
		"employeeNumber": "AEFM34IX",
		"organization": "MyCompany SAS"
  },
	"urn:ietf:params:scim:schemas:extension:javelo:2.0:User": {
    "managerUserName": "[email protected]",
    "status": "Executive",
    "seniorityDate": "2008-01-23T04:56:22Z",
    "contractStartDate": "2000-03-15T04:56:22Z"
  }
}

Here is the response:

{
  "schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:javelo:2.0:User"
	],
  "id": "94fe546f-66e1-4818-88f4-399da170b453",
  "userName": "[email protected]",
  "externalId": "aaeojd012",
  "name": { "givenName": "Bill", "familyName": "Wallace" },
  "emails": [{ "primary": true, "value": "[email protected]" }],
  "displayName": "Bill Wallace",
  "locale": "en-US",
  "active": true,
  "title": "Engineer",
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+18045001160"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Research and Developement",
		"employeeNumber": "AEFM34IX",
		"organization": "MyCompany SAS"
  },
	"urn:ietf:params:scim:schemas:extension:javelo:2.0:User": {
    "managerUserName": "[email protected]",
    "status": "Executive",
    "seniorityDate": "2008-01-23T04:56:22Z",
    "contractStartDate": "2000-03-15T04:56:22Z"
  }
}

PUT - Update

To update a user providing the whole resource, make a PUT request to the endpoint <JAVELO-API>/scim/v2/Users/<USER-ID> with the following payload:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "externalId": "aaeojd012",
  "name": { "givenName": "Bill", "familyName": "Wallace" },
  "emails": [{ "primary": true, "value": "[email protected]" }],
  "displayName": "Bill Wallace",
  "locale": "en-US",
  "active": true,
  "title": "Engineer",
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+18045001160"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Research and Developement",
		"employeeNumber": "AEFM34IX",
		"organization": "MyCompany SAS"
  },
	"urn:ietf:params:scim:schemas:extension:javelo:2.0:User": {
    "managerUserName": "[email protected]",
    "status": "Executive",
    "seniorityDate": "2008-01-23T04:56:22Z",
    "contractStartDate": "2000-03-15T04:56:22Z"
  }
}

Here is the response:

{
  "schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:javelo:2.0:User"
	],
  "id": "94fe546f-66e1-4818-88f4-399da170b453",
  "userName": "[email protected]",
  "externalId": "aaeojd012",
  "name": { "givenName": "Bill", "familyName": "Wallace" },
  "emails": [{ "primary": true, "value": "[email protected]" }],
  "displayName": "Bill Wallace",
  "locale": "en-US",
  "active": true,
  "title": "Engineer",
  "groups": [
    {
      "value": "e9e30dba-f08f-4109-8486-d5c6a331660a",
      "$ref": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a"
    },
    {
      "value": "fc348aa8-3835-40eb-a20b-c726e15c55b5",
      "$ref": "https://example.com/v2/Groups/fc348aa8-3835-40eb-a20b-c726e15c55b5"
    }
  ],
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+18045001160"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Research and Developement",
		"employeeNumber": "AEFM34IX",
		"organization": "MyCompany SAS"
  },
	"urn:ietf:params:scim:schemas:extension:javelo:2.0:User": {
    "managerUserName": "[email protected]",
    "status": "Executive",
    "seniorityDate": "2008-01-23T04:56:22Z",
    "contractStartDate": "2000-03-15T04:56:22Z"
  }
}

PATCH - Update

To update a user's attributes make a PATCH request to the endpoint <JAVELO-API>/scim/v2/Users/<USER-ID> where USER-ID is the target user's javelo UUID sent by Javelo service provider response under the "id" SCIM attributes using the following payload:

 {
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "Replace", "path": "title", "value": "Engineer" },
    { "op": "Replace", "path": "userName", "value": "[email protected]" },
    { "op": "Replace", "path": "name.formatted", "value": "John Smith" },
    { "op": "Replace", "path": "name.familyName", "value": "Smith" },
    { "op": "Replace", "path": "name.givenName", "value": "John" },
    { "op": "Replace", "path": "locale", "value": "en-US" },
    { "op": "Replace", "path": "active", "value": "True" },
    {
      "op": "Replace",
      "path": "phoneNumbers[type eq \"work\"].value",
      "value": "+18045001159"
    },
    {
      "op": "Add",
      "path": "phoneNumbers[type eq \"mobile\"].value",
      "value": "+18042004280"
    },
    { "op": "Replace", "path": "externalId", "value": "008" },
    {
      "op": "Add",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
      "value": "Research and Developement"
    }
  ]
}

Here is the response:

{
  "schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:javelo:2.0:User"
	],
  "id": "94fe546f-66e1-4818-88f4-399da170b453",
  "userName": "[email protected]",
  "externalId": "aaeojd012",
  "name": { "givenName": "Bill", "familyName": "Wallace" },
  "emails": [{ "primary": true, "value": "[email protected]" }],
  "displayName": "Bill Wallace",
  "locale": "en-US",
  "active": true,
  "title": "Engineer",
  "groups": [
    {
      "value": "e9e30dba-f08f-4109-8486-d5c6a331660a",
      "$ref": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a"
    },
    {
      "value": "fc348aa8-3835-40eb-a20b-c726e15c55b5",
      "$ref": "https://example.com/v2/Groups/fc348aa8-3835-40eb-a20b-c726e15c55b5"
    }
  ],
  "phoneNumbers": [
    {
      "primary": true,
      "value": "+18045001160"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Research and Developement",
		"employeeNumber": "AEFM34IX",
		"organization": "MyCompany SAS"
  },
	"urn:ietf:params:scim:schemas:extension:javelo:2.0:User": {
    "managerUserName": "[email protected]",
    "status": "Executive",
    "seniorityDate": "2008-01-23T04:56:22Z",
    "contractStartDate": "2000-03-15T04:56:22Z"
  }
}

DELETE

User profiles are marked as "deactivated" or "activated". This fact means that we never make a DELETE request against a user resource through our SCIM API. Instead, we receive a request to set the active value to false.

💡 More information on the SCIM standard attributes: https://tools.ietf.org/html/rfc7643

⚠️ Once activated, the SCIM provisionning is considered as the only source of truth for creating users. Then you will not be able to login to Javelo with user that was not previously created through SCIM provisionning.

User attributes

Name

Description

Required

Type

Note

userName

The user's unique identifier. It is the identifier the user will use to log into the service

Yes

String

Email format required. Must be unique in the users directory

displayName

The user's full name

No

String

If not provided, default will be the concatenation of name.givenName and name.familyName, separated by a space

title

The user's job title

No

String

name.givenName

The user's first name

Yes

String

name.familiyName

The user's last name

Yes

String

locale

The user's locale for internationalization features.

Yes

String

If not provided, default will be the locale of the company configured in the service provider. Accepted values are: "en", "en-GB", "en-US", "de", "de-DE", "es", "es-ES", "fr", "fr-FR", "nl", "nl-NL"

externalId

A unique identifier that may be used by the SCIM client and service provider to identify a resource

No

String

Some SCIM clients' implementations may use it instead of the userName to filter and identify resources

phoneNumbers[primary eq true].value

The user's phone number

No

String

The client may also pass phoneNumbers[type eq "work"].value.

active

A boolean value indicated if the user is able to log into the service provider

Yes

Boolean

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department

The user's work department

No

String

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber

A string identifier, typically numeric or alphanumeric, assigned to a person, typically based on order of hire or association with an organization.

No

String

In French: "Matricule"

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization

Identifies the name of an organization. The user's juridic organization name.

No

String

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:managerUserName

The userName of the user's manager

No

String

Used to push users hierarchical information into the service provider. The manager must already be provisioned into the service provider for the hierarchical information be provisioned

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:status

The user name status

No

String

Examples: "executive", "associate executive", "intern"

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:seniorityDate

The users's seniority date

No

date_time

Format ISO e.g. "2008-01-23T04:56:22Z". In French: "Date d'ancienneté"

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:contractStartDate

The starting date of the users's active work contract

No

date_time

Format ISO e.g. "2008-01-23T04:56:22Z"

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:grade

grade of the user within the company

No

String

Custom fields

Some fields of SCIM user ressource are mapped on Javelo custom fields. Custom fields is a Javelo feature that allow customer to choose where some data (birth date, title, etc...). Some custom field are initiated by default on Javelo, and some of them are mapped in SCIM interfaces:

SCIM attribute

Custom field

Enabled by default

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department

department

No

phoneNumbers

phone_number

No

title

job

Yes

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization

organization

No

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:status

status

No

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:grade

grade

No

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:seniorityDate

first_hired_on

Yes

urn:ietf:params:scim:schemas:extension:javelo:2.0:User:contractStartDate

current_hired_on

Yes

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber

employee_number

No

Schema customization

Javelo supports a part of SCIM Schema specification. It means each SCIM configuration has its own schema definitition, and we may change it to fit your need. Just ask for it!

Scim Groups

Mapping SCIM group attributes to Javelo's

Scim attribute

Javelo's Team equivalent

id

uuid

displayName

name

members

users

Create Groups

POST /Groups

Create a group with a name and without memberships

POST /scim/v2/Groups HTTP/1.1

Authorization: <Authorization credentials>

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "Test SCIMv2",
    "members": []
}

When it receives this request, the SCIM server responds with the Group object as it would for a GET method request to the /Groups/${groupID}/:

HTTP/1.1 201 CreatedDate: Tue, 10 Sep 2019 04:54:18 GMT
Content-Type: text/json;charset=UTF-8

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
    "displayName": "Test SCIMv2",
    "members": [],
    "meta": {
        "resourceType": "Group"
    }
}

Retrieve Groups

GET /Groups

Retrieve all groups

GET /scim/v2/Groups HTTP/1.1
Authorization: <Authorization credentials>

To paginate use start_index and count params, for example:

GET /scim/v2/Groups?start_index=1&count=3 HTTP/1.1
Authorization: <Authorization credentials>

Then you can retrieve the pagination fields from the response:

 {
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 12,
    "startIndex": 1,
    "itemsPerPage": 3,
    "Resources": [...]
}

Retrieve Specific Groups

GET /Groups/$groupID

Retrieve a group using group's uuid

GET /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b HTTP/1.1
Authorization: <Authorization credentials>

The response looks like:

HTTP/1.1 200 OK
Date: Tue, 10 Sep 2019 05:06:25 GMT
Content-Type: text/json;charset=UTF-8

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
    "displayName": "Test SCIMv2",
    "members":  [{
        "value": "b1c794f24f4c49f4b5d503a4cb2686ea",
        "display": "SCIM 2 Group A"
    }],
    "meta": {
        "resourceType": "Group"
    }
}

Update a specific Group name

PATCH /Groups/$groupID

Update the name of the Group (for updating membership see the next point)

PATCH /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b HTTP/1.1
Authorization: <Authorization credentials>

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "replace",
        "value": {
            "id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
            "displayName": "Test SCIMv2"
        }
    }]
}

That will return the updated Group as a response

HTTP/1.1 200 OK
Date: Tue, 10 Sep 2019 05:08:48 GMT
Content-Type: text/json;charset=UTF-8

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
    "displayName": "Test SCIMv2",
    "members": null,
    "meta": {
        "resourceType": "Group"
    }
}

Update specific Group membership

PATCH /Groups/$groupID

Add and remove a list of users to and from a specific Group

PATCH /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b HTTP/1.1
Authorization: <Authorization credentials>

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
          "op": "remove",
          "path": "members[value eq \"89bb1940-b905-4575-9e7f-6f887cfb368e\"]"
        },
        {
          "op": "add",
          "path": "members",
          "value": [{
              "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173",
              "display": "[email protected]"
        }]
    }]
}

The response will be the updated groups without members

HTTP/1.1 200 OK
Date: Tue, 10 Sep 2019 05:06:25 GMT
Content-Type: text/json;charset=UTF-8

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "abf4dd94-a4c0-4f67-89c9-76b03340cb9b",
    "displayName": "Test SCIMv20",
    "members": null,
    "meta": {
        "resourceType": "Group"
    }
}

It's also possible to replace all memberships of a group in 1 replace operation

PATCH /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b HTTP/1.1
Authorization: <Authorization credentials>

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "members",
      "value": [
        {
          "value": "23a35c27-23d3-4c03-b4c5-6443c09e7173" // user 1 id
        },
        {
          "value": "89bb1940-b905-4575-9e7f-6f887cfb368e" // user 2 id
        }
      ]
    }
  ]
}

Delete a specific Group

DELETE /Groups/$groupID

To delete a Group from Javelo (without deleting users)

DELETE /scim/v2/Groups/abf4dd94-a4c0-4f67-89c9-76b03340cb9b HTTP/1.1
Authorization: <Authorization credentials>

It returns an empty response

HTTP/1.1 204 No Content
Date: Tue, 10 Sep 2019 05:29:25 GMT
Related Articles
Okta with SCIM
Azure Active Directory with SCIM
Microsoft Azure Active Directory
OneLogin
SAML V2.0
Did this answer your question?