Users

Managing users.

User Privileges

There are 4 possible Cloud Conformity roles. Each role grants different levels of access via the api. The roles are:

  • organisation admin
  • organisation user with full access to account
  • organisation user with read-only access to account
  • organisation user with no access to account

User access to each endpoint is listed below:

Endpoint admin full access user read-only user no access user
GET /api-keys (get a list of your api keys) Y Y Y Y
GET /api-keys/id (get details about an api key) Y Y Y Y
POST /accounts (create a new account) Y N N N
GET /accounts (get a list of accounts you have access to) Y Y Y Y
GET /accounts/id Y Y Y N
POST /accounts/id/scan (run the conformity bot) Y Y N N
PATCH /accounts/id/subscription Y N N N
PATCH /accounts/id Y Y N N
GET /accounts/id/settings/rules/ruleId Y Y Y N
PATCH /accounts/id/settings/rules/ruleId Y Y N N
GET /accounts/id/settings/rules Y Y Y N
PATCH /accounts/id/settings/rules Y Y N N
GET /checks * Y Y Y N
POST /checks Y Y N N
DELETE /checks/id Y Y N N
GET /events *** Y Y Y N
POST /external-ids Y N N N
GET /groups Y Y Y N
POST /groups Y N N N
PATCH /groups Y N N N
DELETE /groups Y N N N
GET /resources Y Y N N
GET /settings/communication/accountId ** Y Y Y N
POST /settings/communication ** Y Y N N
PATCH /settings/communication/settingId ** Y Y N N
DELETE /settings/settingId ** Y Y N N
GET /users/whoami Y Y Y Y
GET /users/id Y Y Y Y
GET /users Y N N N
POST /users Y N N N
POST /users/sso Y N N N
PATCH /users/id Y N N N
DELETE /users/id Y N N N
  • The response will depend on the AccountIds added to the query parameter. For example, if a user has no access to an account and they add that account to the AccountIds array, an error will be thrown.

** User role will limit the amount of data they can GET or POST/PATCH. For more information, consult the Settings section.

*** If user role is ADMIN, organisation-level events will also be returned.

Get All Users

get/users

Gets all of the users of the requesting user's organisation. Only ADMINs can perform get all users within the same organisation.

SecurityApiKeyAuth
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

403

Forbidden. This happens when a valid api key is not provided.

Response samples
application/json
{
  • "data": [
    ]
}

Invite a User

post/users

This endpoint is not applicable to users who are part of the Cloud One Platform. Please refer to Cloud One User Management Documentation - Add and manage users to invite new users.

 

This endpoint allows you to invite a user to your organisation.

Please note only accounts (listed inside the accessList) in the request will get updated, existing account permissions are retained. If a new user is invited with the role of USER and an accessList is not provided, the users level permission for all accounts will default to NONE If a user is re-invited with the role of USER, the user will maintain the old account level permissions, unless an accessList is provided to update the permission.

Example Request for inviting a user as an ADMIN:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d
'{
    "data": {
        "attributes": {
            "firstName": "Cool",
            "lastName": "Claude",
            "role": "ADMIN",
            "email": "cc_user@cloudconformity.com"
        }
    }
}'
\
https://us-west-2-api.cloudconformity.com/v1/users

Example Response:

{
    "data": {
        "type": "users",
        "id": "OhnzPVXY",
        "attributes": {
            "first-name": "Cool",
            "last-name": "Claude",
            "role": "ADMIN",
            "email": "cc_user@cloudconformity.com",
            "status": "INVITED",
            "last-login-date": null,
            "created-date": 1575943588002,
            "has-credentials": false
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "A9NDYY12z"
                }
            }
        }
    }
}

Example request for inviting a user with custom permissions:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d
'{
    "data": {
        "attributes": {
            "firstName": "Cool",
            "lastName": "Claude",
            "role": "USER",
            "email": "cc_user@cloudconformity.com",
            "accessList": [
                {
                    "account": "A9_DsY12z",
                    "level": "FULL"
                },
                {
                    "account": "BqdYgfas",
                    "level": "NONE"
                },
                {
                    "account": "kPiASD21",
                    "level": "READONLY"
                }
            ]
        }
    }
}'
\
https://us-west-2-api.cloudconformity.com/v1/users
SecurityApiKeyAuth
Request
Request Body schema: application/json
object

A JSON object containing the following properties

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

422

Unprocessed Entity. Validation error.

Request samples
application/json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Get User Details

get/users/{id}

This endpoint allows you to get the details of the specified user.

Example Response:

{
    "data": {
        "type": "users",
        "id": "CClqMqknVb",
        "attributes": {
            "first-name": "Cool",
            "last-name": "Claude",
            "role": "ADMIN",
            "email": "cc@coolclaude.com",
            "status": "ACTIVE",
            "last-login-date": 1523009079960,
            "created-date": 1499359762438,
            "summary-email-opt-out": true,
            "mobile": "15144008080",
            "mobile-country-code": "CA",
            "mobile-verified": true
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "A9NDYY12z"
                }
            }
        }
    }
}

Example request when an ADMIN queries a USER with custom permissions:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/users/517uNyIvG

Example Response:

{
    "data": {
        "type": "users",
        "id": "517uNyIvG",
        "attributes": {
            "first-name": "Scott",
            "last-name": "Tiger",
            "role": "USER",
            "email": "******@cloudconformity.com",
            "status": "ACTIVE",
            "mfa": false,
            "last-login-date": 1503586843842,
            "created-date": 1485834564224
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "A9NDYY12z"
                }
            },
            "accountAccessList": [
                {
                    "account": "account1",
                    "level": "FULL"
                },
                {
                    "account": "account2",
                    "level": "READONLY"
                },
                {
                    "account": "account3",
                    "level": "FULL"
                },
                {
                    "account": "account4",
                    "level": "NONE"
                },
                {
                    "account": "account5",
                    "level": "NONE"
                },
                {
                    "account": "account6",
                    "level": "NONE"
                }
        }
    }
}
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the user to get.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

403

Forbidden. This happens when a valid api key is not provided.

422

No such user. This happens when the provided id does not belong to any user.

Response samples
application/json
{
  • "data": {
    }
}

Revoke User

delete/users/{id}

This endpoint is not applicable to users who are part of the Cloud One Platform. Please refer to Cloud One User Management Documentation - Delete a user for more information.

 

Revokes a specified user from your organisation.

Only ADMINs can revoke a user within the same organisation.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the user to revoke

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

403

Forbidden. This happens when a valid api key is not provided.

422

No such user. This happens when the provided id does not belong to any user.

Response samples
application/json
{
  • "meta": {
    }
}

Update User Role and Account Access Level

patch/users/{id}

This endpoint is not applicable to users who are part of the Cloud One Platform. Please refer to Cloud One User Management Documentation - Define roles for users for more information.

 

Updates the role and permissions of the specified user.

Only ADMINs can perform the update to other users within the same organisation.

Example Request to set the user's role to ADMIN | USER:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
    "data": {
        "role": "ADMIN"
    }
}
' \
https://us-west-2-api.cloudconformity.com/v1/users/CClqMqknVb \

Example Response

{
    "data": {
        "type": "users",
        "id": "CClqMqknVb",
        "attributes": {
            "first-name": "Cool",
            "last-name": "Claude",
            "role": "ADMIN",
            "email": "cc@coolclaude.com",
            "status": "ACTIVE",
            "last-login-date": 1523009079960,
            "created-date": 1499359762438,
            "summary-email-opt-out": true,
            "mobile": "15144008080",
            "mobile-country-code": "CA",
            "mobile-verified": true
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "A9NDYY12z"
                }
            }
        }
    }
}

Example request to set the user's role to USER and account level access:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
    "data": {
        "role": "USER",
        "accessList": [
            {
                "account": "ad03IHuI_",
                "level": "FULL"
            },
            {
                "account": "Oa1j-gGTX",
                "level": "READONLY"
            },
            {
                "account": "Pa_dgRTA",
                "level": "NONE"
            }
        ]
    }
}
' \
https://us-west-2-api.cloudconformity.com/v1/users/CClqMqknVb \

Example request to set the user's role to USER and updating a specific account level access:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
    "data": {
        "role": "USER",
        "accessList": [
            {
                "account": "ad03IHuI_",
                "level": "READONLY"
            }
        ]
    }
}
' \
https://us-west-2-api.cloudconformity.com/v1/users/CClqMqknVb \

Example Response

{
    "data": {
        "type": "users",
        "id": "CClqMqknVb",
        "attributes": {
            "first-name": "Cool",
            "last-name": "Claude",
            "role": "USER",
            "email": "cc@coolclaude.com",
            "status": "ACTIVE",
            "last-login-date": 1523009079960,
            "created-date": 1499359762438,
            "summary-email-opt-out": true,
            "mobile": "15144008080",
            "mobile-country-code": "CA",
            "mobile-verified": true
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "A9NDYY12z"
                }
            }
        }
    }
}
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the user.

Request Body schema: application/json
object
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

422

Unprocessed Entity. Validation error.

Request samples
application/json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Add SSO User

post/users/sso

This endpoint is not applicable to users who are part of the Cloud One Platform. Please refer to Cloud One User Management Documentation - Add and manage users to invite new users.

 

This endpoint is only available for organisations with an external identity provider setup.

Please note only accounts (listed inside the accessList) in the request will get updated, existing account permissions are retained. If a new user is added with the role of USER and an accessList is not provided, the users level permission for all accounts will default to NONE. If a user is added back into the organisation with the role of USER, the user will maintain the old account level permissions, unless an accessList is provided to update the permission.

Example request for a user with an ADMIN role:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d
'{
    "data": {
        "attributes": {
            "firstName": "sso",
            "lastName": "user",
            "role": "ADMIN",
            "email": "sso_user@cloudconformity.com"
        }
    }
}'
\
https://us-west-2-api.cloudconformity.com/v1/users/sso

Example Response:

{
    "data": {
        "type": "users",
        "id": "abcdefg",
        "attributes": {
            "first-name": "sso",
            "last-name": "user",
            "role": "ADMIN",
            "email": "sso_user@cloudconformity.com",
            "status": "ACTIVE",
            "last-login-date": null,
            "created-date": 1575943588002,
            "has-credentials": false
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "hijklmnop"
                }
            }
        }
    }
}

Example request for adding a user with custom permissions:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d
'{
    "data": {
        "attributes": {
            "firstName": "sso",
            "lastName": "user",
            "role": "USER",
            "email": "sso_user@cloudconformity.com",
            "accessList": [
                {
                    "account": "A9_DsY12z",
                    "level": "FULL"
                },
                {
                    "account": "BqdYgfas",
                    "level": "NONE"
                },
                {
                    "account": "kPiASD21",
                    "level": "READONLY"
                }
            ]
        }
    }
}'
\
https://us-west-2-api.cloudconformity.com/v1/users/sso
SecurityApiKeyAuth
Request
Request Body schema: application/json
object

A JSON object containing the following properties

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

422

Unprocessed Entity. Validation error.

Request samples
application/json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Get The Current User

get/users/whoami

Gets current user.

Example Response:

{
    "data": {
        "type": "users",
        "id": "517uNyIvG",
        "attributes": {
            "first-name": "Scott",
            "last-name": "Tiger",
            "role": "ADMIN",
            "email": "******@cloudconformity.com",
            "status": "ACTIVE",
            "mfa": false,
            "last-login-date": 1503586843842,
            "created-date": 1485834564224
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "A9NDYY12z"
                }
            }
        }
    }
}

Example Request for a USER with custom permissions:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/users/whoami

Example Response:

{
    "data": {
        "type": "users",
        "id": "517uNyIvG",
        "attributes": {
            "first-name": "Scott",
            "last-name": "Tiger",
            "role": "USER",
            "email": "******@cloudconformity.com",
            "status": "ACTIVE",
            "mfa": false,
            "last-login-date": 1503586843842,
            "created-date": 1485834564224
        },
        "relationships": {
            "organisation": {
                "data": {
                    "type": "organisations",
                    "id": "A9NDYY12z"
                }
            },
            "accountAccessList": [
                {
                    "account": "acc1abc",
                    "level": "FULL"
                },
                {
                    "account": "acc2abc",
                    "level": "READONLY"
                },
                {
                    "account": "acc3abc",
                    "level": "FULL"
                }
        }
    }
}
SecurityApiKeyAuth
Responses
200

The request has succeeded

401

Unauthorized. The requesting user does not have enough privilege.

403

Forbidden. This happens when a valid api key is not provided.

Response samples
application/json
{
  • "data": {
    }
}
➔ Next to Well-Architected Tool