Users

You can easily create, update, delete, and read Users in our system. Users have a number of relationships that you should be aware of:

1. Users belong to an Account
2. Users have access to multiple Apps
3. Users can belong to multiple Groups
4. Users can have multiple Devices

Thus, it becomes important that you understand the other facets of our API – that is, Device creation, Group creation, App creation, etc. 

The only required attribute to create a User is a name and email address. You can optionally specify a whether or not they are auto_approved (true or false value is accepted and by default users are auto-approved) and you can specify a welcome message via the message_for_invitation attribute. 

You may specify JSON or XML as an exchange format. XML is default; thus, if you'd like to use JSON, please use HTTP headers Accept and Content-Type.

If you'd like to give a user access to a particular App, you'll need to provide an array of corresponding App Ids. The field name is app_ids; thus, you can give a user the right to an app whose Id is 4e552727a2f8fd000100006f via app_ids: ['4e552727a2f8fd000100006f']

By default, users are given a 48 hour passphrase expiration value. You can override this value by providing an integer value via the field default_passphrase_expiration.

Also by default is that all users must use a passphrase to register a device. You can turn this requirement off via the require_passphrase field by setting it to false. 

Required parameters: name, email

Optional parameters:  message_for_invitation,  auto_approved,  app_ids,  default_passphrase_expiration,  require_passphrase,  group_ids

Endpoint URLs:

If you want to get a list of all users, use an HTTP GET and don't include a :user_idparameter.

For example, if using JSON when creating a User, then the resulting document would look something like:

{ _id: '4f35823b6f4caf3ef1000004',
  account_id: '4d5303e8b8a46d1746000002',
  email: 'user.one.+@mailinator.com',
  group_ids: [],
  name: 'Mr. API User',
  passphrases: 
   [ { _id: '4f35823c6f4caf3ef1000005',
       creation_date: '2012-02-10T15:46:52-05:00',
       passphrase: 'bimoreshi',
       used: false,
       valid_duration_hrs: 48 } ] 
}

As an example of creating an User, here is a Node.js call (written in CoffeeScript) using a RESTful POST:

client = require('restler')

options = { headers: {'X-Token':'ZSUV222zJ9u24CPIg', 'Accept':"application/json", 'Content-Type': 'application/json' } }
createOptions = options
createOptions['data'] = JSON.stringify({user:{ name: "API User", email: "user.one.+@mailinator.com"}})
client.post("http://cirrus.app47.com/api/users", createOptions).on('2XX', (data, response) -> 
  json = JSON.parse(JSON.stringify(data))
  console.log "user id is "  + json['_id'])

And to update the same User, use an HTTP PUT. Note, the User ID in this case was obtained from an earlier call to create the User. The User ID is accordingly placed in the URL (i.e. https://cirrus.app47.com/api/users/080asc23oiuoiuA333)

updateOptions = { headers: {'X-Token':'ZSUV222zJ9u24CPIg', 'Accept':"application/json", 'Content-Type': 'application/json' } }
updateOptions['data'] = JSON.stringify({user:{ name: "Mr. API User", app_ids: ['4e552727a2f8fd000100006f'] }})
client.put("https://cirrus.app47.com/api/users/" + userId, updateOptions)

You can read or GET a User by their ID:

client.get("https://cirrus.app47.com/api/user/" + userId, options).on('2XX', (data, response) -> 
  console.log JSON.parse(JSON.stringify(data)))

In the code above, userId is a valid User ID – the response will look something like:

{ _id: '4f35823b6f4caf3ef1000004',
  account_id: '4d5303e8b8a46d1746000002',
  email: 'user.one.+@mailinator.com',
  group_ids: [],
  name: 'Mr. API User',
  passphrases: 
   [ { _id: '4f35823c6f4caf3ef1000005',
       creation_date: '2012-02-10T15:46:52-05:00',
       passphrase: 'bimoreshi',
       used: false,
       valid_duration_hrs: 48 } ] 
}

Searching by email or name always yields a collection (array) of users. In the case where there is no matching user, you will receive an empty array as the returning payload:

[]

Searches are case independent, meaning the API will match any case for the search term you pass in for name and email address.

You can read or GET an User by the email, which is unique to your account:

client.get("https://cirrus.app47.com/api/users?search=" + emailAddress, options).on('2XX', (data, response) -> 
  console.log JSON.parse(JSON.stringify(data)))

In the code above, emailAddress is a valid User email – the response will look something like:

[
{ _id: '4f35823b6f4caf3ef1000004',
  account_id: '4d5303e8b8a46d1746000002',
  email: 'user.one.+@mailinator.com',
  group_ids: [],
  name: 'Mr. API User',
  passphrases: 
   [ { _id: '4f35823c6f4caf3ef1000005',
       creation_date: '2012-02-10T15:46:52-05:00',
       passphrase: 'bimoreshi',
       used: false,
       valid_duration_hrs: 48 } ] 
}
]

You can read or GET an User by their name, this will perform a search on the name with a case independent criteria:

client.get("https://cirrus.app47.com/api/users?search=" + name, options).on('2XX', (data, response) -> 
  console.log JSON.parse(JSON.stringify(data)))

In the code above, name is a valid User name or partial name – the response will look something like:

[{ _id: '4f35823b6f4caf3ef1000004',
  account_id: '4d5303e8b8a46d1746000002',
  email: 'user.one.+@mailinator.com',
  group_ids: [],
  name: 'Mr. API User',
  passphrases: 
   [ { _id: '4f35823c6f4caf3ef1000005',
       creation_date: '2012-02-10T15:46:52-05:00',
       passphrase: 'bimoreshi',
       used: false,
       valid_duration_hrs: 48 } ] 
}
]

You can also remove a User – just issue an HTTP DELETE and include the User's ID in the URL (just like with GETs and PUTs):

client.del("https://cirrus.app47.com/api/users/" + userId, options).on('2XX', (data, response) -> console.log "user deleted")

You can resend a user's email like so:

curl -XPUT -H "X-Token: your token" 'https://cirrus.app47.com/api/users/resend-email/5134d3eb9404c20002000006' -d ''

where 5134d3eb9404c20002000006 is the User's ID

or

curl -XPUT -H "X-Token: your token" 'https://cirrus.app47.com/api/users/resend-email/bgober@acme%2Ecom' -d ''

Note: You can send the email address but it must be properly encoded – the '.' needs to be %2E and each request must be an HTTP PUT.

If you'd like to resend emails to a lot of users, you can use our bulk resend API. This API is still an HTTP PUT, however, a body is excepted, which contains a list of email addresses. Each email address found in our system will receive an additional app store invite. The benefit of this API call is that you do not need to encode the email address.

The URL is:

https://cirrus.app47.com/api/users/email/resend

To leverage this API, you can send a JSON body like so:

{
   
       "emails": ["aperson@app47.com", "anotherperson@acme.com", "a.person@acme.com", "another.person@acme.com"]
   
}

Note, your XML or JSON can contain 1 to many email addresses. 

You can bulk resend to the users above using cUrl. For example, if the JSON above is in a file dubbed users.json, the cUrl command is:

curl -XPUT -H "X-Token: your_token" -H "Content-Type: application/json" -H "Accept: application/json" https://cirrus.app47.com/api/users/email/resend -d @users.json