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.

email

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

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy