SCIM

Directus partially supports Version 2 of System for Cross-domain Identity Management (SCIM). It is an open standard that allows for the exchange of user information between systems, therefore allowing users to be externally managed using the endpoints described below.

Endpoints
   GET /:project/scim/v2/Users
   GET /:project/scim/v2/Users/:id
  POST /:project/scim/v2/Users
 PATCH /:project/scim/v2/Users/:id
DELETE /:project/scim/v2/Users/:id
   GET /:project/scim/v2/Groups
   GET /:project/scim/v2/Groups/:id
  POST /:project/scim/v2/Groups/:id
 PATCH /:project/scim/v2/Groups/:id
DELETE /:project/scim/v2/Groups/:id

List SCIM Users

List the SCIM users

Parameters

project required

The project you're targetting.

Query

startIndex optional

The 1-based index of the first result in the current set of list results.

count optional

Specifies the desired maximum number of query results per page.

filter optional

Filter by id, userName, emails.value and externalId attributes are supported. Only the eq operator is supported. Uses format ?filter=id eq 15

Endpoint
GET /:project/scim/v2/Users
Response
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 3,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "789",
      "externalId": 1,
      "meta": {
          "resourceType": "User",
          "location": "http://example.com/_/scim/v2/Users/789",
          "version": "W/\"fb2c131da3a58d1f32800c3179cdfe50\""
      },
      "name": {
          "familyName": "User",
          "givenName": "Admin"
      },
      "userName": "admin@example.com",
      "emails": [
          {
              "value": "admin@example.com",
              "type": "work",
              "primary": true
          }
      ],
      "locale": "en-US",
      "timezone": "Europe/Berlin",
      "active": true
    },
    { ... },
    { ... }
  ]
}

Retrieve a SCIM User

Retrieve a single SCIM user by unique identifier.

Parameters

project required

The project you're targetting.

external_id required

The external_id saved in directus_users. Corresponds to the id in the SCIM Users endpoint result.

Query

No query parameters available.

Returns

Returns the SCIM User for the given unique identifier.

Endpoint
   GET /:project/scim/v2/Users/:external_id
Response
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "789",
  "externalId": 1,
  "meta": {
    "resourceType": "User",
    "location": "http://example.com/_/scim/v2/Users/789",
    "version": "W/\"fb2c131da3a58d1f32800c3179cdfe50\""
  },
  "name": {
    "familyName": "User",
    "givenName": "Admin"
  },
  "userName": "admin@example.com",
  "emails": [
    {
      "value": "admin@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "locale": "en-US",
  "timezone": "Europe/Berlin",
  "active": true
}

Create a SCIM User

Create a new SCIM User.

Parameters

project required

The project you're targetting.

Attributes

See the SCIM Specification for more information.

Query

No query parameters available.

Returns

Returns the SCIM User for the user that was just created.

Endpoint
  POST /:project/scim/v2/Users
Request
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "johndoe@example.com",
  "externalId": "johndoe-id",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  }
}
Response
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "johndoe-id",
  "externalId": 4,
  "meta": {
    "resourceType": "User",
    "location": "http://example.com/_/scim/v2/Users/johndoe-id",
    "version": "W/\"fb2c131ad3a58d1f32800c1379cdfe50\""
  },
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "userName": "johndoe@example.com",
  "emails": [
    {
      "value": "johndoe@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "locale": "en-US",
  "timezone": "America/New_York",
  "active": false
}

Update a SCIM User

Update an existing SCIM User

Parameters

project required

The project you're targetting.

external_id required

The external_id saved in directus_users. Corresponds to the id in the SCIM Users endpoint result.

Attributes

See the SCIM Specification for more information.

Query

No query parameters available.

Returns

Returns the SCIM User for the user that was just created.

Endpoint
 PATCH /:project/scim/v2/Users/:external_id
Request
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "name": {
    "familyName": "Doe",
    "givenName": "Johnathan"
  }
}
Response
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "johndoe-id",
  "externalId": 4,
  "meta": {
    "resourceType": "User",
    "location": "http://example.com/_/scim/v2/Users/johndoe-id",
    "version": "W/\"fb2c131ad3a66d1f32800c1379cdfe50\""
  },
  "name": {
    "familyName": "Doe",
    "givenName": "Johnathan"
  },
  "userName": "johndoe@example.com",
  "emails": [
    {
      "value": "johndoe@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "locale": "en-US",
  "timezone": "America/New_York",
  "active": false
}

Delete a SCIM User

Delete an existing SCIM User

Parameters

project required

The project you're targetting.

external_id required

The external_id saved in directus_users. Corresponds to the id in the SCIM Users endpoint result.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/scim/v2/Users/:id

List the SCIM Groups

List the SCIM Groups.

Parameters

project required

The project you're targetting.

Query

startIndex optional

The 1-based index of the first result in the current set of list results.

count optional

Specifies the desired maximum number of query results per page.

filter optional

Filter by id, userName, emails.value and externalId attributes are supported. Only the eq operator is supported. Uses format ?filter=id eq 15

Returns

Returns an array of SCIM Groups.

Endpoint
   GET /:project/scim/v2/Groups
Response
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 3,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "one",
      "externalId": 1,
      "meta": {
        "resourceType": "Group",
        "location": "http://example.com/_/scim/v2/Groups/one",
        "version": "W/\"7b7bc2512ee1fedcd76bdc68926d4f7b\""
      },
      "displayName": "Administrator",
      "members": [
        {
          "value": "admin@example.com",
          "$ref": "http://example.com/_/scim/v2/Users/789",
          "display": "Admin User"
        }
      ]
    },
    { ... },
    { ... }
  ]
}

Retrieve a SCIM Group

Retrieve a single SCIM Group by unique identifier.

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Query

No query parameters available.

Returns

Returns the SCIM Group for the given unique identifier.

Endpoint
   GET /:project/scim/v2/Groups/:id
Response
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "one",
  "externalId": 1,
  "meta": {
    "resourceType": "Group",
    "location": "http://example.com/_/scim/v2/Groups/one",
    "version": "W/\"7b7bc2512ee1fedcd76bdc68926d4f7b\""
  },
  "displayName": "Administrator",
  "members": [
    {
      "value": "admin@example.com",
      "$ref": "http://example.com/_/scim/v2/Users/1",
      "display": "Admin User"
    }
  ]
}

Create a SCIM Group

Create a new SCIM Group.

Parameters

project required

The project you're targetting.

Attributes

See the SCIM Specification for more information.

Query

No query parameters available.

Returns

Returns the SCIM Group for the SCIM Group that was just created.

Endpoint
  POST /:project/scim/v2/Groups/:id
Request
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Editors",
  "externalId": "editors-id"
}
Response
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "editors-id",
  "externalId": 4,
  "meta": {
    "resourceType": "Group",
    "location": "http://example.com/_/scim/v2/Groups/editors-id",
    "version": "W/\"7b7bc2512ee1fedcd76bdc68926d4f7b\""
  },
  "displayName": "Editors",
  "members": []
}

Update a SCIM Group

Update an existing SCIM Group

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Attributes

See the SCIM Specification for more information.

Query

No query parameters available.

Returns

Returns the SCIM Group for the SCIM Group that was just updated.

Endpoint
 PATCH /:project/scim/v2/Groups/:id
Request
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Writers"
}
Response
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "editors-id",
  "externalId": 4,
  "meta": {
    "resourceType": "Group",
    "location": "http://example.com/_/scim/v2/Groups/editors-id",
    "version": "W/\"7b7bc2512ee1fedcd76bdc68926d4f7b\""
  },
  "displayName": "Writers",
  "members": []
}

Delete a SCIM Group

Delete an existing SCIM Group

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/scim/v2/Groups/:id