User provisioning

The User Provisioning API provides an interface for creating new users which can log into the system

Creating a new user in the system

POST /api/users.xml

User creation is done by submitting POST data to our user API controller. The URL for this is:

The POST request needs to have enough information to provision a user and attach them to an account:

Form Parameters:
 
  • email – The email address for the user (must be unique to the system)
  • password – Password to be used by user (min. 6 characters)
  • login – Username to login with (min. 5 characters, must be unique to the system)
  • account_id – Account ID to associate the user to
Status Codes:

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<user>
   <email>user@domain.com</email>
   <password>123456</password>
   <login>username</login>
   <account-id>123456789</account-id>
</user>

Expected Response:

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <account-id type="integer">1464348512</account-id>
  <activated-at type="datetime" nil="true"></activated-at>
  <activation-code nil="true"></activation-code>
  <cached-slug nil="true"></cached-slug>
  <created-at type="datetime">2011-06-20T11:15:59-05:00</created-at>
  <created-by type="integer" nil="true"></created-by>
  <crypted-password>b941e9c8415016e2bd1197ba886d6d40b7e27231</crypted-password>
  <current-site-id type="integer">0</current-site-id>
  <current-step-id type="integer">0</current-step-id>
  <deleted-at type="datetime" nil="true"></deleted-at>
  <email>zem@johnewart.net</email>
  <id type="integer">3830</id>
  <invitation-count type="integer">0</invitation-count>
  <is-seo-pro type="boolean">false</is-seo-pro>
  <is-web-dev type="boolean">false</is-web-dev>
  <last-login-at type="datetime" nil="true"></last-login-at>
  <login>zemdog</login>
  <name></name>
  <opt-out-dashboard type="boolean">false</opt-out-dashboard>
  <password-reset-code nil="true"></password-reset-code>
  <promotion-pending type="boolean">false</promotion-pending>
  <rank-id type="integer">1</rank-id>
  <remember-token nil="true"></remember-token>
  <remember-token-expires-at type="datetime" nil="true"></remember-token-expires-at>
  <salt>7874ff419cbcc99e93f18322be871ce3a2d2112e</salt>
  <state>passive</state>
  <twitter-account nil="true"></twitter-account>
  <updated-at type="datetime">2011-06-20T11:15:59-05:00</updated-at>
  <updated-by type="integer" nil="true"></updated-by>
</user>

Example Ruby Code:

require 'net/http'

user_xml =<<XML
  <?xml version="1.0" encoding="UTF-8"?>
  <user>
     <email>zem@johnewart.net</email>
     <password>quux123</password>
     <login>zemdog</login>
     <account-id>1464348512</account-id>
  </user>
XML

Net::HTTP.start('https://api.upcity.com') {|http|
  req = Net::HTTP::Post.new('/api/users.xml')
  req.basic_auth 'partner_key', 'password'
  req.body = user_xml
  response = http.request(req)
  print response.body
}

Managing User Abilities

Once a user has been associated to your account, you can administer permissions at a granular level. For example, a user may have admin capability across an entire account, or they may only be able to view an individual business or site.

Note that if a user is marked as the owner of an account, they will automatically have all permissions on that account and any of its associated businesses or sites, without an explicit ability needing to be created.

Viewing a User’s Abilities

GET /api/users/(int: user_id)/abilities.json

This call returns an array of all a User’s defined abilities. (See the section on Updating below for more details.)

Status Codes:

Example request:

GET /api/users/1234/abilities.json
Host: upcity.com

Expected Response:

{
  "abilities":[
    {"key":"show","scope_type":"Account","scope_id":123},
    {"key":"show","scope_type":"Site","scope_id":456}
  ]
}

Updating a User’s Abilities

PUT /api/users/(int: user_id)/abilities.json

This call allows you to add, remove, or replace abilities defined for a User. Unless the “merge” or “remove” parameter is passed, this operation will replace the User’s current abilites with the passed-in list.

Form Parameters:
 
  • abilities – Array of hashes containing the key, scope_type, and scope_id of the ability.
  • abilities[].key – The name of the desired ability. The current valid value is “show”
  • abilities[].scope_type – May be one of “Account”, “Business”, or “Site”
  • abilities[].scope_id – The id of the account, business, or site specified by scope_type
Query Parameters:
 
  • merge – If set, these abilities will be added to the User
  • remove – If set, these abilities will be removed from the User
Status Codes:

Example request:

{
  "abilities":[
    {"key":"show","scope_type":"Account","scope_id":123},
    {"key":"show","scope_type":"Site","scope_id":456}
  ]
}

Expected Response:

{
  "abilities":[
    {"key":"show","scope_type":"Account","scope_id":123},
    {"key":"show","scope_type":"Site","scope_id":456}
  ]
}