Create or update an existing principal (a user or group), using the same account as the user making the API call.
Availability
Breeze 4
Description
Creates a principal (a user or group) or updates a standard field for a principal. The principal is created or updated in the same account as the user making the call.
To create a new principal, call principal-update without specifying a principal-id. To update, add the principal-id. Before you update metadata about a principal, call principal-info to get the existing version. In most cases, you need not use a primary type. The principals of primary types are created during the account creation or provisioning step. To create a typical user, use the type user. To create a new user and assign the user as a member of a group such as the administrator group, create the user using principal-update with type ‘user’ and use the group-membership-update API to add the newly created user as a member of a group.
Tip: Do not use the primary built-in groups like administrators, authors, and so on, when creating regular users.
If a principal has custom fields, use acl-field-update to update them, rather than principal-update.
You need Administrator privileges to create or update a principal.
Request URL
http://server_name/api/xml ?action=principal-update &description=string &email=string &first-name=string &has-children=boolean &last-name=string &login=string &name=string &password=string &principal-id=integer &send-email=boolean &type=allowedValue &session=BreezeSessionCookieValue
Parameters
Name |
Type |
Required |
Description |
|---|---|---|---|
| description | String |
N |
The new group’s description. Use only when creating a new group. |
String |
N |
The user’s e-mail address. Can be different from the login. Be sure to specify a value if you use send-email=true. |
|
| first-name | String |
Y/N |
The user’s new first name. Use only with users, not with groups. Required to create a user. |
| has-children | Boolean |
Y |
Whether the principal has children. If the principal is a group, use 1 or true. If the principal is a user, use 0 or false. |
| last-name | String |
Y/N |
The new last name to assign to the user. Required to create a user. Do not use with groups. |
| login | String |
Y/N |
The principal’s new login name, usually the principal’s e-mail address. Must be unique on the server. Required to create or update a user. Do not use with groups. |
| name | String |
Y/N |
The new group’s name. Use only when creating a new group. Required to create a group. |
| password | String |
N |
The new user’s password. Use only when creating a new user. |
| principal-id | String |
Y/N |
The ID of the principal that has information you want to update. Required to update a user or group, but do not use to create either. |
| send-email | Boolean |
N |
A flag indicating whether the server should send an e-mail to the principal with account and login information. |
| type | String |
Y/N |
The type of principal. Use only when creating a new principal (see type for values). |
| session | String |
N |
The value of the BREEZESESSION cookie. Use this parameter if you do not use a client-side cookie management library. |
Filters
Results cannot be filtered or sorted.
Response structure
<?xml version="1.0" encoding="utf-8" ?> <results> <status code=allowedValue /> <principal principal-id=integer account-id=integer has-children=integer type=integer> <login>string</login> <ext-login>string</ext-login> <name>string</name> </principal> </results>
Response values
Element |
Attribute |
Type |
Description |
|---|---|---|---|
| results | Container |
All results the action returns. |
|
| status | Empty, with attributes |
The status of the response. |
|
| code | Allowed value |
A code indicating the response status (see status). |
|
| principal | Container |
Information about the newly created principal. |
|
| principal-id | BIGINT |
The ID of the newly created user. |
|
| account-id | BIGINT |
The ID of the account the new user belongs to. Same as the account of the current user. |
|
| has-children | Boolean |
Whether the principal has children, which indicates whether the principal is a user or group (1 if a group, or 0 if a user). |
|
| type | Allowed value |
The type of principal (see type for values). |
|
| login | String |
The principal’s login ID, often an e-mail address. |
|
| ext-login | String |
The principal’s external authentication ID. By default, the value is the same as login, unless you explicitly set the value to an authentication ID from your network. |
|
| name | String |
The principal’s name. If the principal is a user, concatenated from the first-name and last-name parameters in the request. |
Sample request
https://example.com/api/xml?action=principal-update&first-name=jake &last-name=doe&has-children=0&login=jakedoe@example.com&type=user
Sample response
<?xml version="1.0" encoding="utf-8" ?> <results> <status code="ok" /> <principal principal-id="2006403978" account-id="624520" type="user" has-children="0"> <login>jakedoe@example.com</login> <ext-login>jakedoe@example.com</ext-login> <name>jake doe</name> </principal> </results>
See also
