Users

Note

The Users API can currently only be used by Administrator users.

Listing Users

GET /api2/users
Query Parameters:
 
  • is_admin (optional) – Use 1 to get admin users, and 0 to get non-admin users.
  • email_address (optional) – Filter for users by email address. It must be an exact match to be returned.
  • first_name (optional) – Filter for users by first name. It must be an exact match to be returned.
  • last_name (optional) – Filter for users by last name. It must be an exact match to be returned.
  • unique_id (optional) – Filter for users by unique ID. ‘%’ can be used as a wildcard.
  • group_id (optional) – Filter for users that belong to a specific group.
  • joins (optional) – A comma separated list of links to bundle into the response. Currently, the only supported values are thumbs and groups. See Joining related GET requests.
  • last_login_before (optional) – Filter for users whose last_login_date is before a certain datetime, entered in ISO8601 format. If no timezone is supplied, UTC is assumed.
  • last_login_after (optional) – Filter for users whose last_login_date is after a certain datetime, entered in ISO8601 format. If no timezone is supplied, UTC is assumed.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items" : [
    {
      "id": "2",
      "is_admin": false,
      "email_address": "paul@somedomain.com",
      "display_name": "Paul Lansky",
      "unique_id": "basic:paul@somedomain.com",
      "created_on": "2012-11-09T12:02:47Z",
      "modified_on": "2013-01-18T02:38:48Z",
      "last_login_date": "2015-01-27T00:39:24Z",
      "links": {
        "self": "/api2/users/2",
        "groups": "/api2/groups?user_id=2",
        "thumbs": "/api2/users/2/thumbs"
      }
    },
    {
      "id": "3",
      "is_admin": false,
      "email_address": "norm@somedomain.com",
      "display_name": "Norm MacDonald",
      "unique_id": "basic:norm@somedomain.com",
      "created_on": "2012-11-09T12:02:47Z",
      "modified_on": "2013-01-18T02:38:48Z",
      "last_login_date": "2015-01-27T00:39:24Z",
      "links": {
        "self": "/api2/users/3",
        "groups": "/api2/groups?user_id=3",
        "thumbs": "/api2/users/3/thumbs"
      }
    }
  ],
  "links": {
    "self": "/api2/users?is_admin=false"
  }
}

Fetching a User

GET /api2/users/(user_id)

Fetch an individual user by its unique ID.

Query Parameters:
 
  • joins (optional) – A comma separated list of links to bundle into the response. Currently, the only supported values are thumbs and groups. See Joining related GET requests.

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "2",
  "is_admin": false,
  "email_address": "paul@somedomain.com",
  "display_name": "Paul Lansky",
  "unique_id": "basic:paul@somedomain.com",
  "created_on": "2012-11-09T12:02:47Z",
  "modified_on": "2013-01-18T02:38:48Z",
  "last_login_date": "2015-01-27T00:39:24Z",
  "links": {
    "self": "/api2/users/2",
    "groups": "/api2/groups?user_id=2",
    "thumbs": "/api2/users/2/thumbs"
  }
}

Creating a User

POST /api2/users

Add a new user.

Json Parameters:
 
  • is_admin (required) – Creates user as an admin.
  • email_address (required) – Sets the user’s email address.
  • first_name (required) – Sets the user’s first name.
  • last_name (required) – Sets the user’s last name.
  • password (optional) – Sets the user’s password.
  • unique_id (optional) – Sets the user’s unique ID. If this is missing, the ID will be set to “basic:EMAIL_ADDRESS”, but you can make use of this attribute to provision users for use with different Single Sign-On systems. e.g. “shib:username@domain.edu” might be the unique ID used in your Shibboleth integration with MediaCore. Contact MediaCore support to find out more about this use case.

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api2/users/2

{
  "id": "2",
  "is_admin": false,
  "email_address": "paul@somedomain.com",
  "display_name": "Paul Lansky",
  "unique_id": "basic:paul@somedomain.com",
  "created_on": "2012-11-09T12:02:47Z",
  "modified_on": "2013-01-18T02:38:48Z",
  "last_login_date": "2015-01-27T00:39:24Z",
  "links": {
    "self": "/api2/users/2",
    "groups": "/api2/groups?user_id=2"
  }
}

Updating a User

POST /api2/users/(user_id)

Update a users information.

Note

Setting groups here will replace the old set of groups. To add or remove groups see the add/remove endpoints below.

Json Parameters:
 
  • is_admin (optional) – Updates whether or not the user is an admin.
  • unique_id (optional) – Updates the user’s unique ID (useful when migrating between Single Sign-On integrations).
POST /api2/users/(user_id)/add-groups

Add a user to groups.

Json Parameters:
 
  • group_ids (required) – A JSON list of groups IDs to add the user to.
POST /api2/users/(user_id)/remove-groups

Remove a user from groups.

Json Parameters:
 
  • group_ids (required) – A JSON list of groups IDs to remove the user from.

Deleting a User

DELETE /api2/users/(user_id)

Delete a user.

This endpoint is idempotent; attempting to delete a user that does not exist will return a successful response.

Example Response:

HTTP/1.1 204 No Content

Deleting Multiple Users

DELETE /api2/users/bulk-delete

Delete multiple users.

This endpoint will not allow you to delete the user that is making the request.

This endpoint accepts all the same filter parameters as GET /api2/users.

Example Response:

HTTP/1.1 204 No Content

Previous topic

Tags

Next topic

Groups

This Page