Users APIs

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" : "USER_1@vsphere.local",
  "domain" : "vsphere.local",
  "type" : "USER",
  "role" : {
    "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
  }
}, {
  "name" : "USER_2@vsphere.local",
  "domain" : "vsphere.local",
  "type" : "USER",
  "role" : {
    "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
  }
}, {
  "name" : "SERVICE_USER_1",
  "type" : "SERVICE",
  "role" : {
    "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
  }
} ]'

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" : "USER_1@vsphere.local",
  "domain" : "vsphere.local",
  "type" : "USER",
  "role" : {
    "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
  }
}, {
  "name" : "USER_2@vsphere.local",
  "domain" : "vsphere.local",
  "type" : "USER",
  "role" : {
    "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
  }
}, {
  "name" : "SERVICE_USER_1",
  "type" : "SERVICE",
  "role" : {
    "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
  }
} ]

HTTP Response

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

{
  "elements" : [ {
    "id" : "78e3743a-1e6e-4cdf-abb1-f5aeabe4a79c",
    "name" : "USER_1@vsphere.local",
    "domain" : "vsphere.local",
    "type" : "USER",
    "role" : {
      "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
    },
    "creationTimestamp" : "2024-08-27T20:08:27.023Z"
  }, {
    "id" : "f274ad05-a2b9-48df-b385-d2c7c7bdc7c6",
    "name" : "USER_2@vsphere.local",
    "domain" : "vsphere.local",
    "type" : "USER",
    "role" : {
      "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
    },
    "creationTimestamp" : "2024-08-27T20:08:27.023Z"
  }, {
    "id" : "e22a7541-6e9c-4561-83d5-0999a1e7092c",
    "name" : "SERVICE_USER_1",
    "domain" : "Nil",
    "type" : "SERVICE",
    "apiKey" : "IcUOTTLaUNqaO71PR8Gl0aGVCv9DiL8R",
    "role" : {
      "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
    },
    "creationTimestamp" : "2024-08-27T20:08:27.023Z"
  } ]
}

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" : "b5373fde-0165-4839-8abe-c07fc200ae4c"
  }
} ]'

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" : "b5373fde-0165-4839-8abe-c07fc200ae4c"
  }
} ]

HTTP Response

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

{
  "elements" : [ {
    "id" : "9f79f0b9-0cf4-4356-a3ed-d0e83a44449b",
    "name" : "service_account_1",
    "domain" : "Nil",
    "type" : "SERVICE",
    "apiKey" : "HH3f63awf0dCJwaKiacSVo878DD0TdXL",
    "role" : {
      "id" : "b5373fde-0165-4839-8abe-c07fc200ae4c"
    },
    "creationTimestamp" : "2024-08-27T20:08:25.748Z"
  } ]
}
  • 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" : "78e3743a-1e6e-4cdf-abb1-f5aeabe4a79c",
    "name" : "USER_1@vsphere.local",
    "domain" : "vsphere.local",
    "type" : "USER",
    "role" : {
      "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
    },
    "creationTimestamp" : "2024-08-27T20:08:27.023Z"
  }, {
    "id" : "f274ad05-a2b9-48df-b385-d2c7c7bdc7c6",
    "name" : "USER_2@vsphere.local",
    "domain" : "vsphere.local",
    "type" : "USER",
    "role" : {
      "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
    },
    "creationTimestamp" : "2024-08-27T20:08:27.023Z"
  }, {
    "id" : "e22a7541-6e9c-4561-83d5-0999a1e7092c",
    "name" : "SERVICE_USER_1",
    "domain" : "Nil",
    "type" : "SERVICE",
    "apiKey" : "IcUOTTLaUNqaO71PR8Gl0aGVCv9DiL8R",
    "role" : {
      "id" : "96fa89df-b699-4891-b73c-b6b6754ac503"
    },
    "creationTimestamp" : "2024-08-27T20:08:27.023Z"
  } ]
}

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/78e3743a-1e6e-4cdf-abb1-f5aeabe4a79c' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer etYWRta....'

HTTP Request

DELETE /v1/users/78e3743a-1e6e-4cdf-abb1-f5aeabe4a79c 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" : "242ecfa6-5e9f-46ad-9a14-4e7653042ef1",
    "name" : "ADMIN",
    "description" : "Administrator"
  }, {
    "id" : "bc090b1b-10b2-49e3-82ae-1fa6f48c5d42",
    "name" : "OPERATOR",
    "description" : "Operator"
  }, {
    "id" : "862d7ead-ce6a-4ff3-81d2-65b088c6d710",
    "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" : "USER_1@vsphere.local",
    "name" : "USER_1",
    "type" : "USER"
  }, {
    "id" : "USER_2@vsphere.local",
    "name" : "USER_2",
    "type" : "USER"
  }, {
    "id" : "USER_3@vsphere.local",
    "name" : "USER_3",
    "type" : "USER"
  }, {
    "id" : "USER_4@vsphere.local",
    "name" : "USER_4",
    "type" : "USER"
  }, {
    "id" : "äUSER_5@vsphere.local",
    "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" : "37938f3a-8d5b-474c-bdf0-30410f9f1c25"
  }
}

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-08-27 16:13:54 -0700

Operations
GET
Get Users
Retrieve a list of users from SDDC Manager
POST
Add Users
Assign access to users in SDDC Manager
GET
Get Local Account
Get local account details
DELETE
Disable Local Account
Disable local account
PATCH
Update Local User Password
Update password for local account
GET
Get Ui Users
Retrieve a list of users assigned access via SDDC Manager
GET
Get SSO Domains
Retrieive a list of domains from vCenter Single Sign-On
GET
Get SSO Domain Entities
Retrieve a list of users and groups from a domain in vCenter Single Sign-On
GET
Get Roles
Retrieve a list of roles from SDDC Manager
DELETE
Remove User
Remove access for a user in SDDC Manager