SCIM API
System for Cross-domain Identity Management (SCIM) is an API specification created to facilitate the management of people and groups in cloud-based applications and services.
Invicti SCIM API is built on top of the SCIM 2.0 specification and can be integrated with all Identity Providers. With the Invicti SCIM API, you can create and manage users and teams programmatically.
By using the Invicti SCIM API, you can perform the following operations:
Invicti SCIM API is built on top of the SCIM 2.0 specification and can be integrated with all Identity Providers. With the Invicti SCIM API, you can create and manage users and teams programmatically.
By using the Invicti SCIM API, you can perform the following operations:
- Create users or groups
- Search for users or groups
- Retrieve and update a user’s or group's profile
- Change a user’s password A good password should contain 8 - 256 characters. As you mix lowercase/uppercase letters, digits and special characters it will become stronger. You are also encouraged to use a ➚ pass phrase.
HTTP Basic Authentication
When you make calls to the API, you need to provide your User ID and API Token in the HTTP Basic authentication header; in the form: Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN.
➚ You can get your API credentials by following the steps of "How to Access Your API Credentials".
Bearer Authentication
You can use Base64-encoded (USERID:API-TOKEN) as a bearer authentication token.
When you make calls to the API, you need to provide your User ID and API Token in the HTTP Basic authentication header; in the form: Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN.
➚ You can get your API credentials by following the steps of "How to Access Your API Credentials".
Bearer Authentication
You can use Base64-encoded (USERID:API-TOKEN) as a bearer authentication token.
You can access the API securely via HTTPS. All API requests must specify a Content-Type header of application/scim+json.
Resource URL
Resource URL
You can make the requests to the endpoints below with the specified permissions.
| End Point | Permission |
|---|---|
| scim/v2/users -- /Post/Patch/Put | EditMember |
| scim/v2/users/Get | ViewMemberList |
| scim/v2/users/Delete | DeleteMember |
| scim/v2/groups -- /Post/Patch/Put | AddTeam / EditTeam |
| scim/v2/groups/Get | ViewTeamList |
| scim/v2/groups/Delete | DeleteTeam |
SCIM (Users) lets you create users in Invicti, gives them the proper level of access, and revokes the access for users when they leave your organization or no longer need access to Invicti.
It is possible to filter by the userName eq filter, or providing a valid user email address as the value. See the Filtering section in the SCIM 2.0 specification for details.
Get a single user
Returns information for a single user.The example below retrieves a single User via the "/Users" endpoint.
GET scim/v2/Users/{externalId}
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"userName":"[email protected]",
"name": {
"formatted":"Barbara Jensen",
"familyName":"Jensen",
"givenName":"Barbara"
},
"timezone": "Turkey Standard Time",
"active": true,
"emails": [
{
"type": "work",
"primary": true,
"display": "[email protected]",
"value": "[email protected]"
}
],
"phoneNumbers": [
{
"type": "mobile",
"primary": true,
"display": null,
"value": null
}
],
"displayName": "Barbara Jensen",
"groups": [
{
"type": null,
"primary": false,
"display": "Test Group",
"value": "a035792b-7ed7-4b3a-9883-ae5302e7aa46",
"$ref": null
}
],
"externalId": "2819c223-7f76-453a-919d-413861904646",
"meta": {
"resourceType": "User"
}
}
Get all users
The example below retrieves a single User via the "/Users" endpoint.
GET /scim/v2/Users
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
You can use filtersto specify subsets of users. For example, you can apply the eq (equals) filter parameter to userName to retrieve a specific user or subset of users:
GET /scim/v2/Users?filter=userName+eq+"[email protected]"
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"userName":"[email protected]",
"name": {
"formatted":"Barbara Jensen",
"familyName":"Jensen",
"givenName":"Barbara"
},
"timezone": "Turkey Standard Time",
"active": true,
"emails": [
{
"type": "work",
"primary": true,
"display": "[email protected]",
"value": "[email protected]",
}
],
"phoneNumbers": [
{
"type": "mobile",
"primary": true,
"display": null,
"value": "+905555555555",
"$ref": null
}
],
"displayName": "Start Scan",
"groups": [
{
"primary": false,
"display": "test",
"value": "1858a0c4-2991-44da-b5a4-ada60283ae2a"
},
{
"primary": false,
"display": "Test Group2",
"value": "1c5b102d-b2b8-40b7-cadb-ae5302d00d7e"
}
],
"externalId": "2819c223-7f76-453a-919d-413861904646",
"meta": {
"resourceType": "User",
}
}
],
"startIndex": 0,
"itemsPerPage": 0
}
Create user
Create a new user
POST scim/v2/Users
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
"active": true,
"emails": [{
"primary": true,
"type": "work",
"value": "[email protected]"
}],
"meta": {
"resourceType": "User"
},
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName"
},
}
HTTP/1.1 201 Created
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "48af03ac28ad4fb88478",
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "[email protected]",
"type": "work",
"primary": true
}]
}
Update (Patch) user
Update a user resource with operations on specific attributes, except those that are immutable (userId)
PATCH scim/v2/Users/{externalId}
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "Replace",
"path": "emails[type eq \"work\"].value",
"value": "[email protected]"
},
{
"op": "Replace",
"path": "name.familyName",
"value": "updatedFamilyName"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "6764549bef60420686bc",
"externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
"name": {
"formatted": "givenName updatedFamilyName",
"familyName": "updatedFamilyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "[email protected]",
"type": "work",
"primary": true
}]
}
Update (Put) user
Overwrite the user resource across multiple attributes, except those that are immutable (userId).
PUT scim/v2/Users/{externalId}
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
{
"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"[email protected]",
"active": true,
"name":{
"familyName":"Barbara",
"givenName":"Jane"
},
"userName":"bjensen",
"emails":[
{
"value":"[email protected]"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"userName": "[email protected]",
"name": {
"formatted": "Jane Barbara",
"familyName": "Barbara",
"givenName": "Jane",
},
"timezone": "Turkey Standard Time",
"active": true,
"emails": [
{
"type": "work",
"primary": true,
"display": "[email protected]",
"value": "[email protected]"
}
],
"phoneNumbers": [
{
"type": "mobile",
"primary": true,
"display": null,
"value": null,
"$ref": null
}
],
"displayName": "Jane Barbara",
"groups": [
{
"type": null,
"primary": false,
"display": "test",
"value": "1858a0c4-2991-44da-b5a4-ada60283ae2a",
"$ref": null
},
{
"type": null,
"primary": false,
"display": "Test Group2",
"value": "1c5b102d-b2b8-40b7-cadb-ae5302d00d7e",
"$ref": null
}
],
"externalId": "729f9c5c-0ec3-4938-d055-ab7a01bf54c4",
"meta": {
"resourceType": "User"
}
}
Delete user
All information of the user and user (scans data, profile etc.) are deleted.
DELETE scim/v2/Users/{externalId}
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
204 No Content
If Client attempt to retrieve the previously deleted user.
HTTP/1.1 404 Not Found
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"status": "404"
}
You can perform operations such as creating and updating groups in SCIM (group) and Invicti, and adding users to groups or removing users from groups.
You can use filters to specify subsets of groups. For example, you can apply the sw (starts with) filter parameter to displayName to retrieve a specific group or set of groups.
Get a single group
Returns information for a single group.
The example below retrieves a single Group via the "/Groups" endpoint.
GET scim/v2/Groups/{externalId}
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"displayName": "QA Group",
"members": [
{
"primary": false,
"display": "Scim Test",
"value": "dcfe1154-b0b3-4c00-02cd-abfa03379694",
},
{
"primary": false,
"display": "Test Scim",
"value": "8959ad9a-1b4c-47ad-0d2b-abf702f85c56"
},
],
"externalId": "2819c223-7f76-453a-919d-413861904646",
"meta": {
"resourceType": "Group"
}
}
Get all groups
The example below retrieves a single Group via the "/Groups" endpoint.
GET /scim/v2/Groups
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
You can use filters to specify subsets of groups. For example, you can apply the eq (equals) filter parameter to displayName to retrieve a specific group or subset of groups:
GET /scim/v2/Groups?filter=displayName+co+"test"
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 2,
"startIndex": 1,
"itemsPerPage": 100
"Resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "7d8fd162-3239-4e75-8fc2-4ece6609a770",
"displayName": "Scim Test Team",
"members": [],
"externalId": "7d8fd162-3239-4e75-8fc2-4ece6609a770",
"meta": {
"resourceType": "Group"
}
},
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "5f2824cf-631d-41ca-04b8-abfa033c4b30",
"displayName": "Security Test Team",
"members": [
{
"primary": false,
"display": "Scim User Test1",
"value": "dcfe1154-b0b3-4c00-02cd-abfa03379694"
},
{
"primary": false,
"display": "Scim User Test2",
"value": "8959ad9a-1b4c-47ad-0d2b-abf702f85c56"
},
],
"externalId": "5f2824cf-631d-41ca-04b8-abfa033c4b30",
"meta": {
"resourceType": "Group"
}
}
]
}
Create group
Create a new group
POST scim/v2/Groups
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "SCIM Test Group",
"members": []
}
HTTP/1.1 201 Created
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "95dfa13b-df8e-476e-5064-ae58029b1259",
"displayName": "SCIM Test Group",
"members": [],
"externalId": "95dfa13b-df8e-476e-5064-ae58029b1259",
"meta": {
"resourceType": "Group"
}
}
Update (Patch) group
Can add and remove individual members or groups within the group.
PATCH scim/v2/Groups/{externalId}
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "replace",
"path": "",
"value": {
"displayName": "Test Group 2"
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "2819c223-7f76-453a-919d-413861904646",
"displayName": "Test Group 2",
"members": [],
"externalId": "2819c223-7f76-453a-919d-413861904646",
"meta": {
"resourceType": "Group"
}
}
Update (Put) group
Can add and remove individual members or groups within the group.
PUT scim/v2/Groups/{externalId}
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "SCIM Group3",
"members": [
{
"value": "729f9c5c-0ec3-4938-d055-ab7a01bf54c4"
},
{
"value" :"7b1f9dbfc81649a3255cac4d020fe98a"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": "fcdc30cd-9bfa-4253-08e9-ac0e02a99a40",
"displayName": "SCIM Group3",
"members": [
{
"primary": false,
"display": "Test User 1",
"value": "729f9c5c-0ec3-4938-d055-ab7a01bf54c4"
},
{
"primary": false,
"display": "Test User 2",
"value": "7b1f9dbf-c816-49a3-255c-ac4d020fe98a"
}
],
"externalId": "fcdc30cd-9bfa-4253-08e9-ac0e02a99a40",
"meta": {
"resourceType": "Group"
}
}
Delete group
The group is deleted and the user group dependency is removed. Users in the group are not removed.
DELETE scim/v2/Groups/{externalId}
Host: example.com
Accept: application/scim+json
Authorization: Basic {XXX} where {XXX} is your Base64-encoded USERID:API-TOKEN
204 No Content
If Client attempt to retrieve the previously deleted group.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "404",
"detail": "Resource 'fcdc30cd-9bfa-4253-08e9-ac0e02a99a40' not found."
}
To simplify interoperability, SCIM provides three endpoints to discover supported features and specific attribute details:
-
➚ GET /ServiceProviderConfig , (opens in new window)
Specification compliance, authentication schemes and data models.
-
➚ GET /ResourceTypes , (opens in new window)
An endpoint used to discover the types of resources available.
-
➚ GET /Schemas , (opens in new window)
Introspect resources and attribute extensions.