Managing Users

User names are unique within a specific tenant, and tenant names are unique within the system as a whole.

Topics:

Add User

This API enables you to add new users.

Note:

Only a tenant administrator can add new users.

Method

POST

REST Resource

/user/

URI

https://api_endpoint/user/

Request Body Parameters

Parameter Description
username A unique hierarchical name for a user. For example, /mytenant/myuser.

Object names can contain only alphanumeric characters, hyphens, and periods. Object names are case-sensitive.
fullname Full name of the user
email Valid email address
role (Optional) The role of a user in the system.

This option is used by the cloud administrator. A tenant administrator can discard this option. Oracle Cloud Administrator uses the role option to add one of the following roles to a user:

  • /cloud/admin for cloud administrators.

  • /cloud/monitor for cloud monitors.

  • /tenant_name/admin for tenant administrators.

  • /tenant_name/users for tenant users

If this option is not specified, then the default role of /tenant_name/users is granted.
password (Optional) User password.
The password for a user must meet the following requirements:

  • Alphanumeric.

  • At least 6 characters in length.

  • At least 5 unique characters. For example, "azylaz" is not a valid password but "azylmz" is valid. 

  • Can contain underscore and dash.

  • Must not contain a sequence of characters. For example, "abcde1" and "asdfgh" are not valid passwords. 

  • Must not contain a dictionary word.

Example URI

https://api.oc.example.com/user/

Example Request Body

{
        "username": "/mytenant/myuser", 
        "blacklisted": false, 
        "uri": null, 
        "role": "", 
        "groups": [], 
        "fullname": "myuserfullname", 
        "password": "zaqwsx1234", 
        "email": "myuser@example.com"
}

Example Response Body

{
        "username": "/mytenant/myuser", 
        "customer": "mytenant", 
        "blacklisted": false, 
        "uri": "https://api/user/mytenant/myuser", 
        "id": "f36f54ca-e8d2-4e56-93acae392c4f1", 
        "role": "/mytenant/users", 
        "groups": ["/mytenant/users"], 
        fullname": "myuserfullname", 
        "password": "", 
        "email": "myuser@example.com"
}

Delete User

This API enables you to delete an existing user.

Method

DELETE

REST Resource

/user/name

URI

https://api_endpoint/user/name

URI Parameter

Parameter Description
name Hierarchical name of the user to be deleted. For example, /mytenant/myuser, and /cloud/myuser

Example URI

https://api.oc.example.com/user/mytenant/myuser1

Update User

This API enables you to update user information.

Note:

Tenant users can only update their password and email address.

Method

PUT

REST Resource

/user/name

URI

https://api_endpoint/user/name

URI Parameter

Parameter Description
name A unique hierarchical name for a user. For example, /mytenant/myuser and /cloud/myuser

Request Body Parameters

Parameter Description
fullname (Optional) Full name of the user
email (Optional) Valid email address
role (Optional) The role of a user in the system.

This option is used by the cloud administrator. A tenant administrator can discard this option. A cloud administrator uses the role option to add one of the following roles to a user:

  • /cloud/admin for cloud administrators.

  • /cloud/monitor for cloud monitors.

  • /tenant_name/admin for tenant administrators.

  • /tenant_name/users for tenant users
password (Optional) User password.
The password for a user must meet the following requirements:

  • Alphanumeric.

  • At least 6 characters in length.

  • At least 5 unique characters. For example, "azylaz" is not a valid password but "azylmz" is valid. 

  • Can contain underscore and dash.

  • Must not contain a sequence of characters. For example, "abcde1" and "asdfgh" are not valid passwords. 

  • Must not contain a dictionary word.
blacklisted (Optional) Specifies if the user is blacklisted

Example URI

https://api.oc.example.com/user/mytenant/myuser

Example Request Body

{
        "username": "/mytenant/myuser", 
        "fullname": "myuserfullname", 
        "password": "", 
        "email": "new.email@example.com"
}

Example Response Body

{
        "username": "/mytenant/myuser", 
        "customer": "mytenant", 
        "blacklisted": false, 
        "uri": "https://api/user/mytenant/myuser", 
        "id": "f36f54ca-e8d2-4e56-9371-0acae392c4f1", 
        "role": "/mytenant/users", 
        "groups": ["/mytenant/users"], 
        "fullname": "myuserfullname", 
        "password": "", 
        "email": "new.email@example.com"
}

Retrieve User Details

You can retrieve the user details using REST APIs.

Topics:

Discover Users

This API enables you to discover a list of users in a specific container.

Note:

The discover API calls display the names of the objects in the specified container, not the details about the objects. To list the names of the objects, you must set the Accept header to application/oracle-compute-v3+directory+json. For all other purposes, you must set the Accept header to application/oracle-compute-v3+json.

Method

GET

REST Resource

/user/container

URI

https://api_endpoint/user/container

URI Parameters

Parameter Description
container Hierarchical name-space for users.

Example URI

https://api.oc.example.com/user/

Example Response Body

{"result": ["/mytenant/administrator", "/mytenant/user123"]}

Get User

This API enables you to retrieve information for a specific user.

Method

GET

REST Resource

/user/name

URI

https://api_endpoint/user/name

URI Parameter

Parameter Description
name Hierarchical name of the user. For example, /mytenant/myuser and /cloud/myuser

Example URI

https://api.oc.example.com/user/mytenant/myuser

Example Response Body

{
        "username": "/mytenant/myuser", 
        "customer": "mytenant", 
        "blacklisted": false, 
        "uri": "https://api/user/mytenant/myuser", 
        "id": "f36f54ca-e8d2-4e56-9371-0acae392c4f1", 
        "role": "/mytenant/users", 
        "groups": ["/mytenant/users"], 
        "fullname": "myuserfullname", 
        "password": "", 
        "email": "myuser@example.com"
}

List Users

This API enables you to list users in a specific container.

Note:

You can list only tenant users in your tenancy.

Method

GET

REST Resource

/user/name

URI

https://api_endpoint/user/container?role=roleValue

URI Parameters

Parameter Description
container Hierarchical name-space for the user.
role=roleValue (Optional) The role of a user in the system.
You can filter the list output based on user role by specifying one of the following:

  • /cloud/admin for cloud administrators

  • /cloud/monitor for cloud monitors

  • /tenant_name/admin for tenant administrators

  • /tenant_name/users for tenant users.

Example URI

https://api.oc.example.com/user/mytenant/

Example Response Body

{"result": [
        {
                "username": "/mytenant/administrator", 
                "customer": "mytenant", "blacklisted": false, 
                "uri": "https://api/user/mytenant/administrator", 
                "id": "1ccf2e90-39aa-4b73-bca8-da9fdf8c6441", 
                "role": "/mytenant/admin", 
                "groups": ["/mytenant/admin"], 
                "fullname": "Administrator", "password": "", 
                "email": "myuser@example.com"
        }, 

        {
                "username": "/mytenant/myuser", 
                "customer": "mytenant", 
                "blacklisted": false, 
                "uri": "https://api/user/mytenant/myuser", 
                "id": "f36f54ca-e8d2-4e56-9371-0acae392c4f1", 
                "role": "/mytenant/users", 
                "groups": ["/mytenant/users"], 
                "fullname": "myuserfullname", 
                "password": "", 
                "email": "myuser@example.com"
        }
]}