4.5.1. Create User

Verb	URI	Description
POST	`/instances/{instanceId}/users`	Creates a user for the specified database instance.

Normal Response Code(s): 202

Error Response Code(s): badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), unprocessableEntity (422), instanceFault (500), notImplemented (501), serviceUnavailable (503), itemNotFound (404)

This operation asynchronously provisions a new user for the specified database instance based on the configuration defined in the request object. Once the request is validated and progress has started on the provisioning process, a 202 Accepted response object is returned.

If the corresponding request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 "Bad Request" error response is returned with information regarding the nature of the failure. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.

The following table lists the required and optional attributes for Create User. Refer to the request examples for the required xml/json format:

Table 4.18. Required and Optional Attributes for Create User
Applies To	Name	Description	Required
User	name	Name of the user for the database.	Yes
	password	User password for database access.	Yes
	(database) name	Name of the database that the user can access. One or more database names must be specified.	No
	host	Specifies the host from which a user is allowed to connect to the database. Possible values are a string containing an IPv4 address or "%" to allow connecting from any host. Refer to Section 3.11.1, “User Access Restriction by Host” for details. If `host` is not specified, it defaults to "%".	No

	Notes
	A user is granted all privileges on the specified databases. The following user name is reserved and cannot be used for creating users: root.

Refer to the following tables for information about characters that are valid/invalid for creating database names, user names, and passwords.

Table 4.19. Valid Characters That Can Be Used in a Database Name, User Name, and Password
Character
Letters (upper and lower cases allowed)
Numbers
'@', '?', '#', and spaces are allowed, but not at the beginning and end of the database name, user name, and password
"_" is allowed anywhere in the database name, user name, and password

Table 4.20. Characters That *Cannot* Be Used in a Database Name, User Name, and Password
Character
Single quotes
Double quotes
Back quotes
Semicolons
Commas
Backslashes
Forwardslashes
Spaces at the front or end of the user name or password

Table 4.21. Length Restrictions for Database Name, User Name, and Password
Restriction	Value
Database name maximum length	64
User name maximum length	16
Password maximum length	unlimited (no restrictions)

Table 4.22. Create User Request Parameters
Name	Style	Type	Description
`accountId`	Template	String	The account ID of the owner of the specified instance.
`instanceId`	Template	String	The instance ID for the specified database instance.

The following examples show the Create User requests:

Example 4.61. Create User Request: XML

POST /v1.0/1234/instances/9cccb45e-e15d-4bcc-aedc-61a4bf3e4ad9/users HTTP/1.1
User-Agent: python-reddwarfclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/xml
Content-Type: application/xml

<users xmlns="http://docs.openstack.org/database/api/v1.0">
  <user password="password" name="dbuser1" database="databaseA"/>
  <user host="10.0.0.1" password="password" name="dbuser2">
    <databases>
      <database name="databaseB"/>
      <database name="databaseC"/>
    </databases>
  </user>
  <user password="password" name="dbuser3" database="databaseD"/>
</users>

Example 4.62. Create User Request: JSON

POST /v1.0/1234/instances/dcc5c518-73c7-4471-83e1-15fae67a98eb/users HTTP/1.1
User-Agent: python-reddwarfclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

{
    "users": [
        {
            "database": "databaseA", 
            "name": "dbuser1", 
            "password": "password"
        }, 
        {
            "databases": [
                {
                    "name": "databaseB"
                }, 
                {
                    "name": "databaseC"
                }
            ], 
            "host": "10.0.0.1", 
            "name": "dbuser2", 
            "password": "password"
        }, 
        {
            "database": "databaseD", 
            "name": "dbuser3", 
            "password": "password"
        }
    ]
}

The following examples show the Create User responses:

Example 4.63. Create User Response: XML

HTTP/1.1 202 Accepted
Content-Type: application/xml
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 0
Date: Wed, 08 May 2013 22:43:34 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

Example 4.64. Create User Response: JSON

HTTP/1.1 202 Accepted
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 0
Date: Wed, 08 May 2013 22:43:34 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

Legal notices