Directory Sync

API Reference

Overview

The Directory Sync API is structured around REST semantics. It has predictable, resource-oriented, long-lived URIs. It also uses standard HTTP response status codes and verbs for accessing and modifying content.


Authentication

The Directory Sync API authenticates using your API key. Your team's API key is located in your Developer Dashboard.

API keys are passed using a Bearer token in the Authorization header.

Terminal

file_copy
Authorization: Bearer {secretKey}

Error Codes

WorkOS uses standard HTTP response codes to indicate the success or failure of your API requests.

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate failure, normally due to error caused by incorrect or missing request information (e.g. providing an incorrect API key).

Codes in the 5xx range indicate an error with WorkOS's servers.


Resource Endpoints:

  • GET /directory_users
  • GET /directory_groups

Retrieve a List of Users

Get a complete list of provisioned users.

  • Endpoint: /directory_users?directory=:scim_endpoint_id
  • HTTP Method: GET
  • Body: A paginated list of all provisioned organization users
  • Response: 200 status code

Example Request

Terminal

file_copy
curl --request GET \
 --url https://api.workos.com/directory_users?directory=scim_edp_01E2GQPANEAMZZQDYQ3STMB9WA \
 --header "Authorization: Bearer {secretKey}"

Example Response

JSON

file_copy
{
  "listMetadata" : {
     "before" : null,
     "after" : null
  },
  "data" : [
    {
      "username" : "jan@{foo-corp.com}",
      "last_name" : "Brown",
      "emails" : [
         {
            "primary" : true,
            "type" : "work",
            "value" : "jan@{foo-corp.com}"
         }
      ],
      "raw_attributes" : {
         "schemas" : [
            "urn:scim:schemas:core:1.0"
         ],
         "name" : {
            "familyName" : "Brown",
            "givenName" : "Jan"
         },
         "externalId" : "00u1a0yo3yBBWKTNl357",
         "locale" : "en_US",
         "userName" : "jan@{foo-corp.com}",
         "id" : "scim_usr_01E1JJHG3BFJ3FNRRHSFWEBNCS",
         "displayName" : "Jan Brown",
         "active" : true,
         "groups" : [],
         "meta" : {
            "created" : "2020-02-21T00:32:14.443Z",
            "version" : "7ff066f75718e21a521c269ae7eafce474ae07c1",
            "lastModified" : "2020-02-21T00:36:44.638Z"
         },
         "emails" : [
            {
               "value" : "jan@{foo-corp.com}",
               "type" : "work",
               "primary" : true
            }
         ]
      },
      "id" : "scim_usr_01E1JJHG3BFJ3FNRRHSFWEBNCS",
      "first_name" : "Jan"
   },
   {
      "raw_attributes" : {
         "emails" : [
            {
               "value" : "rosalinda@{foo-corp.com}",
               "type" : "work",
               "primary" : true
            }
         ],
         "meta" : {
            "created" : "2020-02-21T00:32:14.366Z",
            "version" : "dccabf6daf29f2a62a2c5bfe5ef361b27c3b51e7",
            "lastModified" : "2020-02-21T00:36:44.617Z"
         },
         "active" : true,
         "displayName" : "Rosalinda Swift",
         "groups" : [],
         "id" : "scim_usr_01E1JJHG10ANRA2V6PAX3GD7TE",
         "userName" : "rosalinda@{foo-corp.com}",
         "locale" : "en_US",
         "externalId" : "00u1a0ufowBJlzPlk357",
         "name" : {
            "familyName" : "Swift",
            "givenName" : "Rosalinda"
         },
         "schemas" : [
            "urn:scim:schemas:core:1.0"
         ]
      },
      "first_name" : "Rosalinda",
      "id" : "scim_usr_01E1JJHG10ANRA2V6PAX3GD7TE",
      "emails" : [
         {
            "primary" : true,
            "value" : "rosalinda@{foo-corp.com}",
            "type" : "work"
         }
      ],
      "username" : "rosalinda@{foo-corp.com}",
      "last_name" : "Swift"
   }
  ]
}

Retrieve a List of Groups

Get a complete list of provisioned groups.

  • Endpoint: /directory_groups?directory=:scim_endpoint_id
  • HTTP Method: GET
  • Body: A paginated list of all provisioned organization groups
  • Response: 200 status code

Example Request

Terminal

file_copy
curl --request GET \
--url https://api.workos.com/directory_groups?directory=scim_edp_01E2GQPANEAMZZQDYQ3STMB9WA \
--header "Authorization: Bearer {secretKey}"

Example Response

JSON

file_copy
{
  "data" : [
     {
      "name" : "Developers",
      "id" : "scim_grp_01E1JJS84MFPPQ3G655FHTKX6Z"
     }
  ],
  "listMetadata" : {
     "before" : "scim_grp_01E1JJS84MFPPQ3G655FHTKX6Z",
     "after" : "scim_grp_01E1JJS84MFPPQ3G655FHTKX6Z"
  }
}

Retrieve a Single User

Get details for a single provisioned user.

  • Endpoint: /directory_users/:scim_user_id
  • HTTP Method: GET
  • Body: A single provisioned user object
  • Response: 200 status code

Example Request

Terminal

file_copy
curl --request GET \
--url https://api.workos.com/directory_users/scim_usr_01E1JG7J09H96KYP8HM9B0G5SJ \
--header "Authorization: Bearer {secretKey}"

Example Response

JSON

file_copy
{
  "last_name" : "O'Reilly",
  "id" : "scim_usr_01E1JG7J09H96KYP8HM9B0G5SJ",
  "first_name" : "Marcelina",
  "emails" : [
     {
        "value" : "marcelina@{foo-corp.com}",
        "primary" : true,
        "type" : "work"
     }
  ],
  "username" : "marcelina@{foo-corp.com}",
  "raw_attributes" : {
    "displayName" : "Marcelina O'Reilly",
    "externalId" : "00u1lxrrgytXkZ3xT357",
    "active" : true,
    "emails" : [
       {
          "primary" : true,
          "type" : "work",
          "value" : "marcelina@{foo-corp.com}"
       }
    ],
    "schemas" : [
       "urn:scim:schemas:core:1.0"
    ],
    "locale" : "en_US",
    "groups" : [],
    "userName" : "marcelina@{foo-corp.com}",
    "name" : {
       "givenName" : "Marcelina",
       "familyName" : "O'Reilly"
    },
    "meta" : {
       "lastModified" : "2020-02-21T00:36:45.748Z",
       "created" : "2020-02-20T23:51:51.561Z",
       "version" : "5d8be365a12b817198308bea20f7108df602925b"
    },
    "id" : "scim_usr_01E1JG7J09H96KYP8HM9B0G5SJ"
 }
}

Retrieve a Single Group

Get details for a single provisioned group.

  • Endpoint: /directory_groups/:scim_group_id
  • HTTP Method: GET
  • Body: A single provisioned group object
  • Response: 200 status code

Example Request

Terminal

file_copy
curl --request GET \
--url https://api.workos.com/directory_groups/scim_grp_01E1JJS84MFPPQ3G655FHTKX6Z \
--header "Authorization: Bearer {secretKey}"

Example Response

JSON

file_copy
[
  {
     "name" : "Developers",
     "id" : "scim_grp_01E1JJS84MFPPQ3G655FHTKX6Z"
  }
]