Google Git
Sign in
apache / usergrid / 28cad0117254552c786717a52fe4921aef6e6ad1 / . / content / docs / user-management / working-user-data.html
blob: 18f2f0e9273d9d037a3a89601b36ad25115b970b [file] [log] [blame]
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Working with User Data &mdash; Apache Usergrid 2.x documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="top" title="Apache Usergrid 2.x documentation" href="../index.html"/>
<link rel="next" title="Working with group data" href="group.html"/>
<link rel="prev" title="User management &amp; social graph" href="user-management.html"/>
<script src="../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="../index.html" class="icon icon-home"> Apache Usergrid
</a>
<div class="version">
2.x
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Getting Started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../introduction/overview.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/usergrid-features.html">Usergrid Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/data-model.html">Usergrid Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/async-vs-sync.html">Async vs. sync calls</a></li>
</ul>
<p class="caption"><span class="caption-text">Using Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/creating-account.html">Creating a Usergrid Account</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/creating-a-new-application.html">Creating a new application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/using-a-sandbox-app.html">Using a Sandbox Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/using-the-api.html">Using the API</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Storage</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/data-store-dbms.html">The Usergrid Data Store</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/optimizing-access.html">Data Store Best Practices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/collections.html">Collections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/entities.html">Entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Queries</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/querying-your-data.html">Querying your data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/query-parameters.html">Query parameters &amp; clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/operators-and-types.html">Query operators &amp; data types</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/advanced-query-usage.html">Advanced query usage</a></li>
</ul>
<p class="caption"><span class="caption-text">Entity Connections</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/connecting-entities.html">Connecting entities</a></li>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/retrieving-entities.html">Retrieving connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/disconnecting-entities.html">Disconnecting entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Push Notifications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/overview.html">Push notifications overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/adding-push-support.html">Adding push notifications support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/getting-started.html">Getting started with push notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/tutorial.html">Tutorial: Push notifications sample app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/registering.html">Registering with a notification service</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-notifiers.html">Creating notifiers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/managing-users-and-devices.html">Managing users and devices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-and-managing-notifications.html">Creating and managing notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/troubleshooting.html">Troubleshooting</a></li>
</ul>
<p class="caption"><span class="caption-text">Security &amp; Authentication</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/app-security.html">Security &amp; token authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/using-permissions.html">Using permissions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/using-roles.html">Using roles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating users &amp; app clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/user-authentication-types.html">Authentication levels</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/changing-token-time-live-ttl.html">Changing token expiration (time-to-live)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-api-requests.html">Authenticating API requests</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/revoking-tokens-logout.html">Revoking tokens (logout)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/facebook-sign.html">Facebook sign in</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/securing-your-app.html">Security best practices</a></li>
</ul>
<p class="caption"><span class="caption-text">User Management &amp; Social Graph</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="user-management.html">User management &amp; social graph</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Working with User Data</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#creating-users">Creating users</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#request-syntax">Request Syntax</a></li>
<li class="toctree-l3"><a class="reference internal" href="#request-uri">Request URI</a></li>
<li class="toctree-l3"><a class="reference internal" href="#example">Example</a></li>
<li class="toctree-l3"><a class="reference internal" href="#request">Request</a></li>
<li class="toctree-l3"><a class="reference internal" href="#response">Response</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#retrieving-user-data">Retrieving user data</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id1">Request Syntax</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id2">Request URI</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id3">Example</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#updating-deleting-user-data">Updating &amp; deleting user data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#changing-a-user-password">Changing a user password</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id4">Request syntax</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#resetting-a-user-password">Resetting a user password</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#step-1-get-the-password-reset-request-form">STEP 1: Get the password reset request form.</a></li>
<li class="toctree-l3"><a class="reference internal" href="#step-2-display-the-returned-password-reset-request-form-to-the-user">STEP 2: Display the returned password reset request form to the user.</a></li>
<li class="toctree-l3"><a class="reference internal" href="#step-3-let-usergrid-handle-the-rest">STEP 3: Let Usergrid handle the rest!</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="group.html">Working with group data</a></li>
<li class="toctree-l1"><a class="reference internal" href="activity.html">Activity</a></li>
<li class="toctree-l1"><a class="reference internal" href="user-connections.html">Social Graph Connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="user-connections.html#creating-other-connections">Creating other connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="messagee-example.html">App Example - Messagee</a></li>
</ul>
<p class="caption"><span class="caption-text">Geo-location</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../geolocation/geolocation.html">Geolocating your Entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Assets &amp; Files</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/uploading-assets.html">Uploading assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/retrieving-assets.html">Retrieving assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/folders.html">Folders</a></li>
</ul>
<p class="caption"><span class="caption-text">Counters &amp; Events</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/events-and-counters.html">Counters &amp; events</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html">Creating &amp; incrementing counters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html#decrementing-resetting-counters">Decrementing/resetting counters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html#using-counters-hierarchically">Using counters hierarchically</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/retrieving-counters.html">Retrieving counters</a></li>
</ul>
<p class="caption"><span class="caption-text">Organizations &amp; Applications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/managing.html">Organization &amp; application management</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/organization.html">Organization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/application.html">Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/admin-user.html">Admin user</a></li>
</ul>
<p class="caption"><span class="caption-text">API Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html">Methods</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#models">Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#sub-types">Sub-Types</a></li>
</ul>
<p class="caption"><span class="caption-text">Client SDKs</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../sdks/tbd.html">COMING SOON...</a></li>
</ul>
<p class="caption"><span class="caption-text">Installing Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../installation/deployment-guide.html">Usergrid 2.1.0 Deployment Guide</a></li>
</ul>
<p class="caption"><span class="caption-text">More about Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../reference/presos-and-videos.html">Presentations &amp; Videos</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/contribute-code.html">How to Contribute Code &amp; Docs</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Apache Usergrid</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> &raquo;</li>
<li>Working with User Data</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/user-management/working-user-data.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="working-with-user-data">
<h1>Working with User Data<a class="headerlink" href="#working-with-user-data" title="Permalink to this headline"></a></h1>
<p>You can store and manage user data as User entities. With user data in
your application, you can add support for a wide variety of features
common to mobile apps. For example, you can:</p>
<ul class="simple">
<li>Control access to data by defining permission rules. (See <a class="reference external" href="../security-and-auth/app-security.html">Security &amp;
token authentication</a> for
more.)</li>
<li>Present content specific to each user, such as their list of
favorites.</li>
<li>Support social features, such as letting users &#8220;follow&#8221; one another,
for example.</li>
</ul>
<p>In mobile applications, data about users is typically added by users
themselves when they register through your app. The topics in this
section provide specific cURL and SDK-specific examples for getting
things done with user data.</p>
<div class="section" id="creating-users">
<h2>Creating users<a class="headerlink" href="#creating-users" title="Permalink to this headline"></a></h2>
<p>A user entity represents an application user. Using API Services you can
create, retrieve, update, delete, and query user entities. See <a class="reference external" href="../rest-endpoints/api-doc.html#user">User
entity properties</a> for a list of
the system-defined properties for user entities. In addition, you can
create user properties specific to your application.</p>
<div class="section" id="request-syntax">
<h3>Request Syntax<a class="headerlink" href="#request-syntax" title="Permalink to this headline"></a></h3>
<div class="highlight-python"><div class="highlight"><pre>curl -X POST &quot;https://api.usergrid.com/your-org/your-app/users&quot; -d &#39;{ &quot;username&quot;: &quot;john.doe&quot;, &quot;email&quot;: &quot;john.doe@gmail.com&quot;, &quot;name&quot;: &quot;John Doe&quot;, &quot;password&quot;: &quot;test1234&quot; }&#39;
</pre></div>
</div>
<p>Use the POST method to create a new user in the users collection.</p>
</div>
<div class="section" id="request-uri">
<h3>Request URI<a class="headerlink" href="#request-uri" title="Permalink to this headline"></a></h3>
<div class="highlight-python"><div class="highlight"><pre>POST /&lt;org_id&gt;/&lt;app_id&gt;/users
</pre></div>
</div>
<p>Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="69%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>uuid | org_id</td>
<td>Organization UUID or organization name.</td>
</tr>
<tr class="row-odd"><td>uuid | app_id</td>
<td>Application UUID or application name.</td>
</tr>
<tr class="row-even"><td>request body</td>
<td>One or more sets of user properties.</td>
</tr>
</tbody>
</table>
<p>The username is mandatory and must be unique. Here&#8217;s an example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">&quot;username&quot;</span> <span class="p">:</span> <span class="s">&quot;john.doe&quot;</span><span class="p">,</span>
<span class="s">&quot;email&quot;</span> <span class="p">:</span> <span class="s">&quot;john.doe@gmail.com&quot;</span><span class="p">,</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;John Doe&quot;</span><span class="p">,</span>
<span class="s">&quot;password&quot;</span> <span class="p">:</span> <span class="s">&quot;test1234&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Although the password parameter is not mandatory, if you don&#8217;t specify
it, the user will not be able to log in using username and password
credentials. If a password is not specified for the user, and you&#8217;re an
Admin, you can set a password for the user (see <a class="reference external" href="#changing-a-user-password">Changing a User
Password</a>).</p>
<p>__ Note__: The username can contain any combination of characters,
including those that represent letters, numbers, and symbols.</p>
</div>
<div class="section" id="example">
<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline"></a></h3>
<p><strong>Note</strong>: Although not shown in the API examples below, you need to
provide a valid access token with each API call. See <a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating
users and application
clients</a>
for details.</p>
</div>
<div class="section" id="request">
<h3>Request<a class="headerlink" href="#request" title="Permalink to this headline"></a></h3>
<div class="highlight-python"><div class="highlight"><pre>curl -X POST &quot;https://api.usergrid.com/my-org/my-app/users&quot; -d &#39;{&quot;username&quot;:&quot;john.doe&quot;,&quot;email&quot;:&quot;john.doe@gmail.com&quot;,&quot;name&quot;:&quot;John Doe&quot;}&#39;
</pre></div>
</div>
</div>
<div class="section" id="response">
<h3>Response<a class="headerlink" href="#response" title="Permalink to this headline"></a></h3>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">&quot;action&quot;</span> <span class="p">:</span> <span class="s">&quot;post&quot;</span><span class="p">,</span>
<span class="s">&quot;application&quot;</span> <span class="p">:</span> <span class="s">&quot;db1e60a0-417f-11e3-9586-0f1ff3650d20&quot;</span><span class="p">,</span>
<span class="s">&quot;params&quot;</span> <span class="p">:</span> <span class="p">{</span> <span class="p">},</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/users&quot;</span><span class="p">,</span>
<span class="s">&quot;uri&quot;</span> <span class="p">:</span> <span class="s">&quot;https://api.usergrid.com/steventraut/mynewapp/users&quot;</span><span class="p">,</span>
<span class="s">&quot;entities&quot;</span> <span class="p">:</span> <span class="p">[</span> <span class="p">{</span>
<span class="s">&quot;uuid&quot;</span> <span class="p">:</span> <span class="s">&quot;8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc&quot;</span><span class="p">,</span>
<span class="s">&quot;type&quot;</span> <span class="p">:</span> <span class="s">&quot;user&quot;</span><span class="p">,</span>
<span class="s">&quot;name&quot;</span> <span class="p">:</span> <span class="s">&quot;John Doe&quot;</span><span class="p">,</span>
<span class="s">&quot;created&quot;</span> <span class="p">:</span> <span class="mi">1390533228622</span><span class="p">,</span>
<span class="s">&quot;modified&quot;</span> <span class="p">:</span> <span class="mi">1390533228622</span><span class="p">,</span>
<span class="s">&quot;username&quot;</span> <span class="p">:</span> <span class="s">&quot;john.doe&quot;</span><span class="p">,</span>
<span class="s">&quot;email&quot;</span> <span class="p">:</span> <span class="s">&quot;john.doe@gmail.com&quot;</span><span class="p">,</span>
<span class="s">&quot;activated&quot;</span> <span class="p">:</span> <span class="n">true</span><span class="p">,</span>
<span class="s">&quot;picture&quot;</span> <span class="p">:</span> <span class="s">&quot;http://www.gravatar.com/avatar/e13743a7f1db7f4246badd6fd6ff54ff&quot;</span><span class="p">,</span>
<span class="s">&quot;metadata&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc&quot;</span><span class="p">,</span>
<span class="s">&quot;sets&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">&quot;rolenames&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/roles&quot;</span><span class="p">,</span>
<span class="s">&quot;permissions&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/permissions&quot;</span>
<span class="p">},</span>
<span class="s">&quot;collections&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="s">&quot;activities&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/activities&quot;</span><span class="p">,</span>
<span class="s">&quot;devices&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/devices&quot;</span><span class="p">,</span>
<span class="s">&quot;feed&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/feed&quot;</span><span class="p">,</span>
<span class="s">&quot;groups&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/groups&quot;</span><span class="p">,</span>
<span class="s">&quot;roles&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/roles&quot;</span><span class="p">,</span>
<span class="s">&quot;following&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/following&quot;</span><span class="p">,</span>
<span class="s">&quot;followers&quot;</span> <span class="p">:</span> <span class="s">&quot;/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/followers&quot;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}],</span>
<span class="s">&quot;timestamp&quot;</span> <span class="p">:</span> <span class="mi">1390533228619</span><span class="p">,</span>
<span class="s">&quot;duration&quot;</span> <span class="p">:</span> <span class="mi">142</span><span class="p">,</span>
<span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="s">&quot;my-org&quot;</span><span class="p">,</span>
<span class="s">&quot;applicationName&quot;</span> <span class="p">:</span> <span class="s">&quot;my-app&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="retrieving-user-data">
<h2>Retrieving user data<a class="headerlink" href="#retrieving-user-data" title="Permalink to this headline"></a></h2>
<p>You can retrieve data about users through cURL or one of the SDKs. Each
provides a way to filter the list of users by data associated with the
user, such as username or UUID, or other properties in the user entity.</p>
<p>See <a class="reference external" href="../rest-endpoints/api-doc.html#user">User entity properties</a> for
a list of the system-defined properties for user entities. In addition,
you can create user properties specific to your application.</p>
<div class="section" id="id1">
<h3>Request Syntax<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h3>
<div class="highlight-python"><div class="highlight"><pre>curl -X GET &quot;https://api.usergrid.com/your-org/your-app/users&quot;
</pre></div>
</div>
<p>Use the GET method to retrieve user data.</p>
</div>
<div class="section" id="id2">
<h3>Request URI<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h3>
<div class="highlight-python"><div class="highlight"><pre>GET /&lt;org_id&gt;/&lt;app_id&gt;/users/&lt;uuid | username | email_address | ?ql=query_string&gt;
</pre></div>
</div>
<p>Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="69%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>uuid | org_id</td>
<td>Organization UUID or organization name</td>
</tr>
<tr class="row-odd"><td>uuid | app_id</td>
<td>Application UUID or application name</td>
</tr>
<tr class="row-even"><td>user identifier</td>
<td>User UUID, username, or email address.</td>
</tr>
</tbody>
</table>
<p>The alias <code class="docutils literal"><span class="pre">/users/me</span></code> can be used in place of the current user’s uuid,
username, or email address. Note: The <code class="docutils literal"><span class="pre">/users/me</span></code> endpoint is
accessible only if you provide an access token with the request (see
<a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating users and application
clients</a>).
If you make an anonymous (&#8220;guest&#8221;) call, the system will not be able to
determine which user to return as <code class="docutils literal"><span class="pre">/users/me</span></code>.</p>
<p><strong>Note</strong>: The username can contain any combination of characters,
including those that represent letters, numbers, and symbols.</p>
</div>
<div class="section" id="id3">
<h3>Example<a class="headerlink" href="#id3" title="Permalink to this headline"></a></h3>
<p><strong>Note</strong>: Although not shown in the API examples below, you need to
provide a valid access token with each API call. See <a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating
users and application
clients</a>
for details.</p>
<p>Requests</p>
<div class="highlight-python"><div class="highlight"><pre># Get a user by username.
curl -X GET &quot;https://api.usergrid.com/my-org/my-app/users/jane.doe&quot;
# Get a user by UUID.
curl -X GET &quot;https://api.usergrid.com/my-org/my-app/users/a407b1e7-58e8-11e1-ac46-22000a1c5a67e&quot;
# Get a user by email.
curl -X GET &quot;https://api.usergrid.com/my-org/my-app/users/jane.doe@gmail.com&quot;
# Get user data filtering by their city property value.
curl -X GET &quot;https://api.usergrid.com/my-org/my-app/users?ql=select%20*%20where%20adr.city%3D&#39;Chicago&#39;&quot;
</pre></div>
</div>
<p>Response</p>
<div class="highlight-python"><div class="highlight"><pre>{
&quot;action&quot; : &quot;get&quot;,
&quot;application&quot; : &quot;1c8f60e4-da67-11e0-b93d-12313f0204bb8&quot;,
&quot;params&quot; : {
&quot;_&quot;: [
&quot;1315524419746&quot;
]
},
&quot;path&quot; : &quot;https://api.usergrid.com/12313f0204bb-1c8f60e4-da67-11e0-b93d/1c8f60e4-da67-11e0-b93d-12313f0204bb/users&quot;,
&quot;uri&quot; : &quot;https://api.usergrid.com/005056c00008-4353136f-e978-11e0-8264/4353136f-e978-11e0-8264-005056c00008/users&quot;,
&quot;entities&quot; : [ {
&quot;uuid&quot; : &quot;78c54a82-da71-11e0-b93d-12313f0204b&quot;,
&quot;type&quot; : &quot;user&quot;,
&quot;created&quot; : 1315524171347008,
&quot;modified&quot; : 1315524171347008,
&quot;activated&quot; : true,
&quot;email&quot; : &quot;jane.doe@gmail.com&quot;,
&quot;metadata&quot; : {
&quot;path&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb&quot;,
&quot;sets&quot; : {
&quot;rolenames&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/rolenames&quot;,
&quot;permissions&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/permissions&quot;
},
&quot;collections&quot; : {
&quot;activities&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/activities&quot;,
&quot;devices&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/devices&quot;,
&quot;feed&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/feed&quot;,
&quot;groups&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/groups&quot;,
&quot;roles&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/roles&quot;,
&quot;following&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/following&quot;,
&quot;followers&quot; : &quot;/users/78c54a82-da71-11e0-b93d-12313f0204bb/followers&quot;
}
},
&quot;username&quot; : &quot;jane.doe&quot;
}
... Additional entities here if data for multiple users was returned...
],
&quot;timestamp&quot; : 1315524421071,
&quot;duration&quot; : 107,
&quot;organization&quot; : &quot;my-org&quot;,
&quot;applicationName&quot;: &quot;my-app&quot;
}
</pre></div>
</div>
</div>
</div>
<div class="section" id="updating-deleting-user-data">
<h2>Updating &amp; deleting user data<a class="headerlink" href="#updating-deleting-user-data" title="Permalink to this headline"></a></h2>
<p>To update or delete a user, perform an update or delete on the
associated user entity as you would any other entity. For more
information and code samples, see <a class="reference external" href="../data-storage/entities.html#updating-data-entities">Updating Data
Entities</a> and
<a class="reference external" href="../data-storage/entities.html#deleting-data-entities">Deleting Data
Entities</a>.</p>
</div>
<div class="section" id="changing-a-user-password">
<h2>Changing a user password<a class="headerlink" href="#changing-a-user-password" title="Permalink to this headline"></a></h2>
<p>Changing a user&#8217;s password</p>
<div class="section" id="id4">
<h3>Request syntax<a class="headerlink" href="#id4" title="Permalink to this headline"></a></h3>
<div class="highlight-python"><div class="highlight"><pre>curl -X PUT https://api.usergrid.com/&lt;org&gt;/&lt;app&gt;/users/&lt;username_or_email&gt;/password -d &#39;{oldpassword:&lt;old_password&gt;,newpassword:&lt;new_password&gt;}&#39;
</pre></div>
</div>
<p>Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="76%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>org</td>
<td>Organization UUID or organization name</td>
</tr>
<tr class="row-odd"><td>app</td>
<td>Application UUID or application name</td>
</tr>
<tr class="row-even"><td>username_or_email</td>
<td>Username or email of the user entity whose password you want to reset.</td>
</tr>
<tr class="row-odd"><td>old_password</td>
<td>User entity&#8217;s old password.</td>
</tr>
<tr class="row-even"><td>new_password</td>
<td>User entity&#8217;s new password.</td>
</tr>
</tbody>
</table>
<p><strong>Note</strong>: If your request is authenticated with an application-level
token, then <code class="docutils literal"><span class="pre">old_password</span></code> is not required. For more, see <a class="reference external" href="../security-and-auth/authenticating-users-and-application-clients.html#application-client-authentication">Application
client
authentication</a>.</p>
<p>Example request</p>
<div class="highlight-python"><div class="highlight"><pre>curl -X PUT https://api.usergrid.com/my-org/my-app/users/john.doe/password -d &#39;{&quot;newpassword&quot;:&quot;foo9876a&quot;,&quot;oldpassword&quot;:&quot;bar1234b&quot;}&#39;
</pre></div>
</div>
<p>Example response</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">&quot;action&quot;</span><span class="p">:</span> <span class="s">&quot;set user password&quot;</span><span class="p">,</span>
<span class="s">&quot;timestamp&quot;</span><span class="p">:</span> <span class="mi">1355185897894</span><span class="p">,</span>
<span class="s">&quot;duration&quot;</span><span class="p">:</span> <span class="mi">47</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="resetting-a-user-password">
<h2>Resetting a user password<a class="headerlink" href="#resetting-a-user-password" title="Permalink to this headline"></a></h2>
<p>Resetting a user&#8217;s password</p>
<p>Usergrid provides a standard password reset flow that can be implemented
to allow a user to reset their password without having to provide their
old password. The most common use of this would be a &#8216;Forgot password?&#8217;
feature in your app.</p>
<p>Note that you can also implement your own password reset flow using
application-level authentication and the /password endpoint. For more,
see <a class="reference external" href="#changing-a-user-password">Changing a user password</a>.</p>
<p>To use the Usergrid password reset flow, do the following:</p>
<div class="section" id="step-1-get-the-password-reset-request-form">
<h3>STEP 1: Get the password reset request form.<a class="headerlink" href="#step-1-get-the-password-reset-request-form" title="Permalink to this headline"></a></h3>
<p>Make a GET request to the following:</p>
<div class="highlight-python"><div class="highlight"><pre>/users/&lt;username&gt;/resetpw
</pre></div>
</div>
<p>For example, using cURL, a request to reset the password for a user with
username &#8216;someUser&#8217; would look like this:</p>
<div class="highlight-python"><div class="highlight"><pre>curl -x GET https://api.usergrid.com/your-org/your-app/users/someUser/resetpw
</pre></div>
</div>
</div>
<div class="section" id="step-2-display-the-returned-password-reset-request-form-to-the-user">
<h3>STEP 2: Display the returned password reset request form to the user.<a class="headerlink" href="#step-2-display-the-returned-password-reset-request-form-to-the-user" title="Permalink to this headline"></a></h3>
<p>The request to <code class="docutils literal"><span class="pre">/resetpw</span></code> will return the HTML for the standard
Usergrid password reset request form that you will display to your user.
The request form requires the users to provide their username as well as
answer a standard CAPTCHA challenge:</p>
<div class="highlight-python"><div class="highlight"><pre>&lt;!DOCTYPE html PUBLIC &quot;-//W3C//DTD HTML 4.01 Transitional//EN&quot; &quot;http://www.w3.org/TR/html4/loose.dtd&quot;&gt;
&lt;html&gt;
&lt;head&gt;
&lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=ISO-8859-1&quot;&gt;
&lt;title&gt;Reset Password&lt;/title&gt;
&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;/css/styles.css&quot; /&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;div class=&quot;dialog-area&quot;&gt;
&lt;form class=&quot;dialog-form&quot; action=&quot;&quot; method=&quot;post&quot;&gt;
&lt;fieldset&gt;
&lt;p&gt;
Enter the captcha to have your password reset instructions sent to
someUser@adomain.com
&lt;/p&gt;
&lt;p id=&quot;human-proof&quot;&gt;&lt;/p&gt;
&lt;script type=&quot;text/javascript&quot; src=&quot;https://www.google.com/recaptcha/api/challenge?k=6LdSTNESAAAAAKHdVglHmMu86_EoYxsJjqQD1IpZ&quot;&gt;&lt;/script&gt;
&lt;p class=&quot;buttons&quot;&gt;
&lt;input type=&quot;submit&quot; value=&quot;submit&quot; /&gt;
&lt;/p&gt;
&lt;/fieldset&gt;
&lt;/form&gt;
&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre></div>
</div>
<p>You can apply any additional styling you wish to the form to make it
match the style of your app before displaying it to the user.</p>
</div>
<div class="section" id="step-3-let-usergrid-handle-the-rest">
<h3>STEP 3: Let Usergrid handle the rest!<a class="headerlink" href="#step-3-let-usergrid-handle-the-rest" title="Permalink to this headline"></a></h3>
<p>Once the user submits the form with their username, they will receive an
email from Usergrid that contains a link to the password reset form,
where they can specify a new password. The user entity will be updated
immediately.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="group.html" class="btn btn-neutral float-right" title="Working with group data" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="user-management.html" class="btn btn-neutral" title="User management &amp; social graph" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2013-2015, Apache Usergrid.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'2.x',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>