SCIM API
  • 7 minutes to read
  • Dark
    Light
  • PDF

SCIM API

  • Dark
    Light
  • PDF

Article summary

This article presents how senhasegura's System for Cross-domain Identity Management (SCIM) endpoints share information using API calls.

Info

Any tool that supports the SCIM 2.0 protocol can be integrated with senhasegura.

GET Service Provider Configuration

Request

To retrieve the Service Provider Configuration, send a request to the following endpoint:

GET /iso/scim/v2/ServiceProviderConfig

Parameters

No parameters.

Return

Returns the configurations supported by our SCIM connector.

Sample response

{
    "schemas":  ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
    "documentationUri": "http://example.com/help/scim.html",
    "patch": {
      "supported":true
    },
    "bulk": {
      "supported":true,
      "maxOperations":1000,
      "maxPayloadSize":1048576
    },
    "filter": {
      "supported":true,
      "maxResults": 200
    },
    "changePassword": {
      "supported":false
    },
    "sort": {
      "supported":true
    },
    "etag": {
      "supported":true
    },
    "authenticationSchemes": [
      {
        "name": "OAuth Bearer Token",
        "description":
          "Authentication scheme using the OAuth Bearer Token Standard",
        "specUri": "http://www.rfc-editor.org/info/rfc6750",
        "documentationUri": "http://example.com/help/oauth.html",
        "type": "oauthbearertoken",
        "primary": true
      },
      {
        "name": "HTTP Basic",
        "description":
          "Authentication scheme using the HTTP Basic Standard",
        "specUri": "http://www.rfc-editor.org/info/rfc2617",
        "documentationUri": "http://example.com/help/httpBasic.html",
        "type": "httpbasic"
       }
    ],
    "meta": {
      "location": "https://example.com/v2/ServiceProviderConfig",
      "resourceType": "ServiceProviderConfig",
      "created": "2010-01-23T04:56:22Z",
      "lastModified": "2011-05-13T04:42:34Z",
      "version": "W\/\"3694e05e9dff594\""
    }
  }
Info

For more information, check the RFC 7643.


GET Resource Types

Request

To retrieve the Resource Types, send a request to the following endpoint:
GET /iso/scim/v2/ResourceTypes

Parameters

No parameters.

Return

Returns the Resource Types supported by our SCIM connector.

Sample response

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 1,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
      ],
      "id": "User",
      "name": "User",
      "endpoint": "/Users",
      "description": "https://tools.ietf.org/html/rfc7643#section-8.7.1",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
          "required": false
        }
      ],
      "meta": {
        "location": "https://vault.senhasegura.com/iso/scim/v2/ResourceTypes/User",
        "resourceType": "ResourceType"
      }
    }
  ]
}
Info

For more information, check the RFC 7644.


GET User Resource Type

Request

To retrieve the User Resource Type, add the object at the end of the URI and send a request to the following endpoint:
GET /iso/scim/v2/ResourceTypes/User

Parameters

No parameters.

Return

Returns the attributes associated with user objects.

Sample response

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
  ],
  "id": "User",
  "name": "User",
  "endpoint": "/Users",
  "description": "https://tools.ietf.org/html/rfc7643#section-8.7.1",
  "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemaExtensions": [
    {
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "required": false
    }
  ],
  "meta": {
    "location": "https://vault.senhasegura.com/iso/scim/v2/ResourceTypes/User",
    "resourceType": "ResourceType"
  }
}

GET Schemas

Request

To retrieve the Schemas, send a request to the following endpoint:
GET /iso/scim/v2/Schemas

Parameters

No parameters.

Return

Returns the Schemas supported by our SCIM connector.

Sample response

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 3,
  "itemsPerPage": 3,
  "startIndex": 1,
  "Resources": [
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:User",
      "name": "User",
      "description": "User Schema",
      "attributes": [
        "..."
      ],
      "meta": {
        "resourceType": "Schema",
        "location": "https://vault.senhasegura.com/iso/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
      }
    }
  ]
}

GET User Schema

Request

To retrieve the User Schema, add the specifications at the end of the URI and send a request to the following endpoint:
GET /iso/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User

Parameters

No parameters.

Return

Returns information about the Schema associated with the user.

Sample response

{
  "id": "urn:ietf:params:scim:schemas:core:2.0:User",
  "name": "User",
  "description": "User Schema",
  "attributes": [
    {
      "name": "userName",
      "type": "string",
      "multiValued": false,
      "required": true,
      "caseExact": false,
      "mutability": "readWrite",
      "returned": "default",
      "uniqueness": "server",
      "description": "Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users."
    },
    {
      "name": "name",
      "type": "complex",
      "multiValued": false,
      "required": false,
      "mutability": "readWrite",
      "returned": "default",
      "uniqueness": "none",
      "description": "The components of the user's real name. Providers MAY return just the full name as a single string in the formatted sub-attribute, or they MAY return just the individual component attributes using the other sub-attributes, or they MAY return both.  If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component attributes should be combined.",
      "subAttributes": [
        {
          "name": "formatted",
          "type": "string",
          "multiValued": false,
          "required": false,
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none",
          "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g., 'Ms. Barbara J Jensen, III')."
        },
        {
          "name": "familyName",
          "type": "string",
          "multiValued": false,
          "required": false,
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none",
          "description": "The family name of the User, or last name in most Western languages (e.g., 'Jensen' given the full name 'Ms. Barbara J Jensen, III')."
        }
.
.
.
}
  ],
  "meta": {
    "resourceType": "Schema",
    "location": "https://wdc.test.host/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
  }
}
Info

For more information, check the RFC 7643.


GET Users

Request

To retrieve the Users, send a request to the following endpoint:
GET /iso/scim/v2/Users

Parameters

No parameters.

Return

Returns the list of users.

Sample response

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "itemsPerPage": 25,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
      ],
      "id": "2",
      "externalId": "SCIM1",
      "userName": "Jane Doe",
      "meta": {
        "resourceType": "User",
        "created": "2018-04-17T09:03:39-05:00",
        "lastModified": "2018-04-17T09:03:39-05:00",
        "location": "https://vault.senhasegura.com/iso/scim/v2/Users/2"
      },
      "name": {
        "familyName": "Doe",
        "givenName": "Jane",
        "honorificPrefix": "Mrs",
        "honorificSuffix": "MD",
        "formatted": "Mrs Jane Doe MD"
      },
      "displayName": "Jane Doe",
      "nickName": "Nick Jane",
      "profileUrl": "http://skimmer.com/jane",
      "title": "First Class Skimmer",
      "...": "..."
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
      ],
      "id": "1",
      "externalId": "SCIM2",
      "userName": "Card Skimmer",
      "meta": {
        "resourceType": "User",
        "created": "2018-04-17T09:03:12-05:00",
        "lastModified": "2018-04-17T09:03:12-05:00",
        "location": "https://<account>.4me.com/scim/v2/Users/1"
      },
      "name": {
        "familyName": "Skimmer",
        "givenName": "Card",
        "honorificPrefix": "Sir",
        "honorificSuffix": "MD",
        "formatted": "Sir Card Skimmer MD"
      },
      "displayName": "Card Skimmer",
      "nickName": "Nicked Name",
      "...": "..."
    }
  ]
}

GET User by ID

Request

To retrieve a specific User, send a request to the following endpoint:
GET /iso/scim/v2/Users/:id

Parameters

NameTypeRequiredDescriptionExample
idIntegerRequiredSpecifies the user inside the system."id": "2"

Return

Returns information about a specific user.

Sample response

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "2",
  "externalId": "SCIM1",
  "userName": "Jane Doe",
  "meta": {
    "resourceType": "User",
    "created": "2018-04-17T09:03:39-05:00",
    "lastModified": "2018-04-17T09:03:39-05:00",
    "location": "https://vault.senhasegura.com/iso/scim/v2/Users/2"
  },
  "name": {
    "familyName": "Doe",
    "givenName": "Jane",
    "honorificPrefix": "Mrs",
    "honorificSuffix": "MD",
    "formatted": "Mrs Jane Doe MD"
  },
  "displayName": "Jane Doe",
  "nickName": "Nick Jane",
  "profileUrl": "http://skimmer.com/jane",
  "title": "First Class Skimmer",
  "userType": "Skimmer",
  "preferredLanguage": "Dutch",
  "locale": "nl",
  "timezone": "Amsterdam",
  "active": true,
  "emails": [
    {
      "type": "work",
      "value": "[email protected]",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "type": "work",
      "value": "+31 65 7777777",
      "primary": true
    },
    {
      "type": "personal",
      "value": "+31 20 4444444"
    }
  ],
  "photos": [
    {
      "value": "photo1"
    }
  ],
  "entitlements": [
    {
      "value": "specialist"
    },
    {
      "value": "change_manager"
    },
    {
      "value": "service_manager"
    }
  ],
  "groups": [
    {
      "value": "Full access"
    },
    {
      "value": "With approval"
    }
  ]
}

POST Users

Request

To create Users, send a request to the following endpoint:
POST /iso/scim/v2/Users

Parameters

NameTypeRequiredDescriptionExample
userNameStringRequiredThe unique login identifier for the user."dschrute"
externalIdStringRequiredAn external identifier for the user."12345"
name.formattedStringRequiredThe full name of the user."Dwight Schrute"
name.familyNameStringOptionalThe family name or last name of the user."Schrute"
name.givenNameStringOptionalThe given name or first name of the user."Dwight"
phoneNumbers.valueStringOptionalThe user's phone number."+1 (555) 123-4567"
emails.valueStringRequiredThe user's email address."[email protected]"
emails.typeStringOptionalThe category of the email address."work"
emails.primaryBooleanOptionalIndicates whether the email address is the user's primary email.true
entitlements.valueStringOptionalThe user's role in the system."Assistant Regional Manager"
groups.valueStringOptionalThe user groups associated with the user."Sales Team"

Return

Returns the created users and the associated information when successful.

Sample response

HTTP/1.1 201 Created

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id":"2819c223-7f76-453a-919d-413861904646",
  "externalId":"dschrute",
  "meta":{
    "resourceType":"User",
    "created":"2011-08-01T21:32:44.882Z",
    "lastModified":"2011-08-01T21:32:44.882Z",
    "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
    "version":"W\/\"e180ee84f0671b1\""
  },
  "name":{
    "familyName":"Schrute",
    "givenName":"Dwight"
  },
  "userName":"dschrute"
}
Caution

If the user's password is included in the request, the user must use that password. Otherwise, you should generate a random password, and the administrator must log in to senhasegura to modify it and share it with the user.


PATCH Users

Request

To modify information about Users, send a request to the following endpoint:
PATCH /iso/scim/v2/Users:id

Parameters

NameTypeRequiredDescriptionExample
userNameStringRequiredThe unique login identifier for the user."dschrute"
externalIdStringRequiredAn external identifier for the user."12345"
name.formattedStringRequiredThe full name of the user."Dwight Schrute"
name.familyNameStringOptionalThe family name or last name of the user."Schrute"
name.givenNameStringOptionalThe given name or first name of the user."Dwight"
phoneNumbers.valueStringOptionalThe user's phone number."+1 (555) 123-4567"
emails.valueStringRequiredThe user's email address."[email protected]"
emails.typeStringOptionalThe category of the email address."work"
emails.primaryBooleanOptionalIndicates whether the email address is the user's primary email.true
entitlements.valueStringOptionalThe user's role in the system."Assistant Regional Manager"
groups.valueStringOptionalThe user groups associated with the user."Sales Team"

Return

Returns the updated information associated with the users.

Sample response

HTTP/1.1 200 OK

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id":"2819c223-7f76-453a-919d-413861904646",
  "externalId":"dschrute",
  "meta":{
    "resourceType":"User",
    "created":"2011-08-01T21:32:44.882Z",
    "lastModified":"2011-08-01T21:32:44.882Z",
    "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
    "version":"W\/\"e180ee84f0671b1\""
  },
  "name":{
    "familyName":"Schrute",
    "givenName":"Dwight"
  },
  "userName":"dschrute"
}

DELETE Users

Request

To remove Users, send a request to the following endpoint:
DELETE /iso/scim/v2/Users/:id

Parameters

No parameters.

Return

If the user deletion was successful, it will return the 'HTTP 204 No Content' response.

Sample response

HTTP/1.1 204 No Content

Was this article helpful?