Users APIs

APIs for managing Users

Table of Contents

• Add users

• Add service users

• Get the Users

• Delete a User

• Get the Roles

• Get SSO Domain

• Get SSO Domain entities

• Get local account details

• Update password for local account

1. Add users

• This API is used to add users.

1.1. Prerequisites API

The following data is required

• Name of the SSO or AD domain

• Username

• Type of the user. For types supported, refer to User

• Role ID

1.2. Steps API

• Fetch the role ID for the role.

Tip : Refer to Get the Roles

• Invoke the API to add a user.

Note : For the sake of brevity, the Bearer tokens in the Authorization header has been abbreviated in the code snippets throughout this document.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/users' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....' \
    -d '[ {
  "name" : "[email protected]",
  "domain" : "vsphere.local",
  "type" : "USER",
  "role" : {
    "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
  }
}, {
  "name" : "[email protected]",
  "domain" : "vsphere.local",
  "type" : "USER",
  "role" : {
    "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
  }
}, {
  "name" : "SERVICE_USER_1",
  "type" : "SERVICE",
  "role" : {
    "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
  }
} ]'

HTTP Request

POST /v1/users HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 437
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

[ {
  "name" : "[email protected]",
  "domain" : "vsphere.local",
  "type" : "USER",
  "role" : {
    "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
  }
}, {
  "name" : "[email protected]",
  "domain" : "vsphere.local",
  "type" : "USER",
  "role" : {
    "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
  }
}, {
  "name" : "SERVICE_USER_1",
  "type" : "SERVICE",
  "role" : {
    "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
  }
} ]

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 884

{
  "elements" : [ {
    "id" : "5f16d078-e42e-428a-ae95-dde7bc56b134",
    "name" : "[email protected]",
    "domain" : "vsphere.local",
    "type" : "USER",
    "role" : {
      "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
    },
    "creationTimestamp" : "2024-06-21T02:44:09.664Z"
  }, {
    "id" : "4f025e18-3388-4b89-a235-998523741866",
    "name" : "[email protected]",
    "domain" : "vsphere.local",
    "type" : "USER",
    "role" : {
      "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
    },
    "creationTimestamp" : "2024-06-21T02:44:09.664Z"
  }, {
    "id" : "16c8483b-8515-41a3-a844-46c3545547bc",
    "name" : "SERVICE_USER_1",
    "domain" : "Nil",
    "type" : "SERVICE",
    "apiKey" : "CQGo5o8t1FrpODzMmQkBQ2mVwx1S8T5m",
    "role" : {
      "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
    },
    "creationTimestamp" : "2024-06-21T02:44:09.664Z"
  } ]
}

1.3. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API

2. Add service users

• This API is used to add service users.

2.1. Prerequisites API

The following data is required

• Username

• Type of the user. The type would be SERVICE for service users. For types supported, refer to User.

• Role ID

2.2. Steps API

• Fetch the role ID for the role.

Tip : Refer to Get the Roles

• Invoke the API to create a service user.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/users' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....' \
    -d '[ {
  "name" : "service_account_1",
  "type" : "SERVICE",
  "role" : {
    "id" : "ec9c0d40-0315-42f1-8c8b-9bd16503d66c"
  }
} ]'

HTTP Request

POST /v1/users HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 128
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

[ {
  "name" : "service_account_1",
  "type" : "SERVICE",
  "role" : {
    "id" : "ec9c0d40-0315-42f1-8c8b-9bd16503d66c"
  }
} ]

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 337

{
  "elements" : [ {
    "id" : "4092d0be-a1c2-4fd0-8878-63ceebf1b119",
    "name" : "service_account_1",
    "domain" : "Nil",
    "type" : "SERVICE",
    "apiKey" : "UHQ4ZrPmuPdZhZ9WoO25i8KQTtAM0RW1",
    "role" : {
      "id" : "ec9c0d40-0315-42f1-8c8b-9bd16503d66c"
    },
    "creationTimestamp" : "2024-06-21T02:44:07.572Z"
  } ]
}

• The response of the API contains the apiKey . With the apiKey, the service user can login and obtain access token.

Obtain access token for a service user

2.3. Prerequisites API

The following data is required

• API key

2.4. Steps API

• Invoke the API with the API key to generate an access token and refresh token.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/tokens' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "username" : "automationapp",
  "apiKey" : "6598S0SIQC04sGjEr0nIeDlZx18GYRoT"
}'

HTTP Request

POST /v1/tokens HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 83
Host: sfo-vcf01.rainpole.io

{
  "username" : "automationapp",
  "apiKey" : "6598S0SIQC04sGjEr0nIeDlZx18GYRoT"
}

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 683

{
  "accessToken" : "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxNTFlZWI5Yy1mNWNmLTQ3N2UtYTJhYS0yMzg4ZmFmYzMwNDAiLCJpYXQiOjE1ODIxMzgzMzQsInN1YiI6ImFkbWluaXN0cmF0b3JAdnNwaGVyZS5sb2NhbCIsImlzcyI6InZjZi1hdXRoIiwiYXVkIjoic2RkYy1zZXJ2aWNlcyIsIm5iZiI6MTU4MjEzODMzNCwiZXhwIjoxNTgyMTQxOTM0LCJ1c2VyIjoiYWRtaW5pc3RyYXRvckB2c3BoZXJlLmxvY2FsIiwibmFtZSI6ImFkbWluaXN0cmF0b3JAdnNwaGVyZS5sb2NhbCIsInNjb3BlIjpbIkJBQ0tVUF9DT05GSUdfUkVBRCIsIkNSRURFTlRJQUxfUkVBRCIsIlVTRVJfV1JJVEUiLCJPVEhFUl9XUklURSIsIkJBQ0tVUF9DT05GSUdfV1JJVEUiLCJPVEhFUl9SRUFEIiwiVVNFUl9SRUFEIiwiQ1JFREVOVElBTF9XUklURSJdfQ.ylzrCyo4ymTKtSv1flmUrW-b8mxjRl7T2uV3a8sWWMA",
  "refreshToken" : {
    "id" : "3c6b3c30-3bf2-480b-9539-8483699ab911"
  }
}

2.5. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API

3. Get the Users

• This API is used to get all the users listed in the system.

• This also gives other details associated with the user like domain, type of user and the role id.

3.1. Steps API

• Invoke the API to fetch all users.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/users' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

GET /v1/users HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 884

{
  "elements" : [ {
    "id" : "5f16d078-e42e-428a-ae95-dde7bc56b134",
    "name" : "[email protected]",
    "domain" : "vsphere.local",
    "type" : "USER",
    "role" : {
      "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
    },
    "creationTimestamp" : "2024-06-21T02:44:09.664Z"
  }, {
    "id" : "4f025e18-3388-4b89-a235-998523741866",
    "name" : "[email protected]",
    "domain" : "vsphere.local",
    "type" : "USER",
    "role" : {
      "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
    },
    "creationTimestamp" : "2024-06-21T02:44:09.664Z"
  }, {
    "id" : "16c8483b-8515-41a3-a844-46c3545547bc",
    "name" : "SERVICE_USER_1",
    "domain" : "Nil",
    "type" : "SERVICE",
    "apiKey" : "CQGo5o8t1FrpODzMmQkBQ2mVwx1S8T5m",
    "role" : {
      "id" : "d826989f-3129-4c6c-a71d-0a9b28c9de04"
    },
    "creationTimestamp" : "2024-06-21T02:44:09.664Z"
  } ]
}

3.2. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API

4. Delete a User

• This API is used to delete a user.

4.1. Prerequisites API

The following data is required

• User ID

4.2. Steps API

• Invoke the API with the "user ID" to be deleted.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/users/5f16d078-e42e-428a-ae95-dde7bc56b134' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

DELETE /v1/users/5f16d078-e42e-428a-ae95-dde7bc56b134 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

HTTP Response

HTTP/1.1 204 No Content

4.3. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API

5. Get the Roles

• This API is used to fetch all the roles supported by VCF.

• Currently there are three roles that are supported - ADMIN, OPERATOR and VIEWER.

5.1. Prerequisites API

None

5.2. Steps API

• Invoke the API to fetch the roles and role IDs

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/roles' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

GET /v1/roles HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 361

{
  "elements" : [ {
    "id" : "6dcd4db7-21e7-464f-a86f-7453d645f1a3",
    "name" : "ADMIN",
    "description" : "Administrator"
  }, {
    "id" : "42cf424e-0cd3-472e-9473-78afc1bfa833",
    "name" : "OPERATOR",
    "description" : "Operator"
  }, {
    "id" : "d020dd1e-4a10-4bc6-ba03-08cfaca76769",
    "name" : "VIEWER",
    "description" : "Viewer"
  } ]
}

5.3. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API

6. Get SSO Domain

• This API is used to fetch the SSO domains known to the system.

6.1. Prerequisites API

None

6.2. Steps API

• Invoke the API by specifying the "SSO domain name".

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/sso-domains' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

GET /v1/sso-domains HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 38

{
  "elements" : [ "vsphere.local" ]
}

6.3. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API

7. Get SSO Domain entities

• This API is used to fetch all domain entities in a particular domain known to the system.

• This includes users and subdomains.

7.1. Prerequisites API

The following data is required

• SSO Domain name

7.2. Steps API

• Invoke the API by specifying the "SSO domain name".

Note : To search for a particular user or subdomain set the query parameter searchCriteria.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/sso-domains/vsphere.local/entities?entityName=USER' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

GET /v1/sso-domains/vsphere.local/entities?entityName=USER HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 786

{
  "elements" : [ {
    "id" : "[email protected]",
    "name" : "USER_1",
    "type" : "USER"
  }, {
    "id" : "[email protected]",
    "name" : "USER_2",
    "type" : "USER"
  }, {
    "id" : "[email protected]",
    "name" : "USER_3",
    "type" : "USER"
  }, {
    "id" : "[email protected]",
    "name" : "USER_4",
    "type" : "USER"
  }, {
    "id" : "ä[email protected]",
    "name" : "äUSER_5",
    "type" : "USER"
  }, {
    "id" : "vsphere.local\\\\group_1",
    "name" : "",
    "type" : "GROUP"
  }, {
    "id" : "vsphere.local\\\\group_2",
    "name" : "",
    "type" : "GROUP"
  }, {
    "id" : "vsphere.local\\\\group_3",
    "name" : "",
    "type" : "GROUP"
  }, {
    "id" : "vsphere.local\\\\group_4",
    "name" : "",
    "type" : "GROUP"
  } ]
}

7.3. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API

8. Get local account details

• This API is used to check whether or not the local account is configured.

8.1. Prerequisites API

None

8.2. Steps API

• Invoke the API to check whether or not the local account is configured.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/users/local/admin' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

GET /v1/users/local/admin HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 141

{
  "isConfigured" : false,
  "name" : "admin@local",
  "type" : "USER",
  "role" : {
    "id" : "3215e21e-ac79-42ea-8b0e-9dc7cee08577"
  }
}

8.3. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API

9. Update password for local account

• This API is used to update the local account password or to configure local account if it wasn't configured during the bringup

9.1. Prerequisites API

• The following data is required

  • Old Password

  • New Password

Note : Provide only "newPassword" if you are configuring the local account for the first time.

• New password must be in compliance with these password policies.

  Password requirements:

  • Length: 12-127 characters

  • Allowed special characters: ! % @ $ ^ # ? *

  • At least 1 small letter, capital letter, number and special character should be present

  • At least 2 alphabetic characters should be present

  • A character cannot be repeated more than 3 times consecutively

9.2. Steps API

• Invoke the API to update the local account password or to configure local account.

cURL Request

$ curl 'https://sfo-vcf01.rainpole.io/v1/users/local/admin' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....' \
    -d '{
  "oldPassword" : "XXXXXXX",
  "newPassword" : "YYYYYYY"
}'

HTTP Request

PATCH /v1/users/local/admin HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 60
Host: sfo-vcf01.rainpole.io
Authorization: Bearer etYWRta....

{
  "oldPassword" : "XXXXXXX",
  "newPassword" : "YYYYYYY"
}

HTTP Response

HTTP/1.1 204 No Content

9.3. Related APIs API

[_getusers] API [_addusers] API [_removeuser] API [_getroles] API [_getssodomains] API [_getssodomainentities] API [_getlocalaccount] API [_updatelocaluserpassword] API
Last updated 2024-06-21 01:22:12 -0700

Operations

POST

Add Users

Assign access to users in SDDC Manager

DELETE

Disable Local Account

Disable local account

GET

Get Local Account

Get local account details

GET

Get Roles

Retrieve a list of roles from SDDC Manager

GET

Get SSO Domain Entities

Retrieve a list of users and groups from a domain in vCenter Single Sign-On

GET

Get SSO Domains

Retrieive a list of domains from vCenter Single Sign-On

GET

Get Ui Users

Retrieve a list of users assigned access via SDDC Manager

GET

Get Users

Retrieve a list of users from SDDC Manager

DELETE

Remove User

Remove access for a user in SDDC Manager

PATCH

Update Local User Password

Update password for local account