Users APIs
APIs for managing Users
Table of Contents
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