Directus Docs

# 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.

# 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 (opens new window) 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 (opens new window) 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 (opens new window) 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 (opens new window) 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

← Server →