Author Identity API
Identity Management
These APIs allows an application server to query and update existing user identities. Please see the oauth /provision
APIs for information about the user creation process.
Query Semantics
For all identity APIs, Query operations are passed in the query-string of the URL. Each operation can be either a simple equality constraints (e.g name=Ruby
) or more flexible query operators following the form op(val)
(e.g age=gt(18)
). Here is a full list of supported query operators:
eq
matches the exact value provided, and is the default operator when none is providedgt
- greater thangte
- greater than or equal tolt
- less thanlte
- less than or equal tone
- not equalexists
- checks for the existence of the given fieldtype
- checks the type of the given field. Valid types include array, bool, date, decimal, double, int, long, null, object, objectId, regex, string, and timestampregex
- find by regular expressionsize
- match array fields of the given size
Note that you can include duplicate query-string parameters to further refine the constraints on a particular field. For instance, age=gt(18)&age=lt(30)
will limit results to users between the ages of 18 and 30 (exclusive).
Search
GET /identity
The search API allows you to run simple queries against your user base. The result set will be determined by the query-string (as described above). In addition to user fields, the query-string may also contain skip
and limit
keys. When set, these keys should be given integer values greater than zero. skip
will omit the first n
results from the query, and limit
will ensure that at most n
results are returned. This provides a means of paginating results.
example
Find all users who have logged in less than 5 times
curl -X GET -H "Content-Type: application/json" -H "Bearer <server JWT>" \
https://aum.iris.comcast.net/identity?number_times_login=lt(5)
Sample output:
200
[
{
"user_name": "jj54321",
"first_name": "John",
"last_name": "Smith",
"...": "..."
"number_times_login": 3,
},
{
"user_name": "sj01234",
"first_name": "Sarah",
"last_name": "Johnson",
"...": "..."
"number_times_login": 0,
}
]
Fetch
GET /identity/{userid}
Fetch allows you to retrieve a single user based on userid
.
example
Get the user with id 1234
curl -X GET -H "Content-Type: application/json" -H "Bearer <server JWT>" \
https://aum.iris.comcast.net/identity/1234
Sample output:
200
{
"first_name": "Zach",
"last_name": "Robertson",
"...": "..."
}
Bulk Update
PUT /identity
This endpoint provides a means of updating many users at once. The set of users to be updated will be determined by the query-string (as described above).
example
Normalize the nickname
field when the value is blank (^(\s*)$
).
curl -X GET -H "Content-Type: application/json" -H "Bearer <server JWT>" \
-d '{"nickname": ""}'
https://aum.iris.comcast.net/identity?nickname=regex(%5E(%5Cs*)%24)
Sample output:
200
{
"matched": 10,
"updated": 7
}
Update
PUT /identity/{userid}
Use this endpoint to update a single user.
example
Update the given user's phone number.
curl -X GET -H "Content-Type: application/json" -H "Bearer <server JWT>" \
-d '{"phone_number": "111-222-3344"}'
https://aum.iris.comcast.net/identity/1234
Sample output:
200
{
"phone_number": "111-222-3344",
"...": "..."
}