Table of contents

Users and Groups API

Users API

You can create and manage users with a RESTful interface in the GrayMeta Platform, with the following object and endpoints

User Object

{
    "id": "5833031d7d551417c16891d475429de3",
    "email": "testuser@graymeta.com",
    "first_name": "Morgan",
    "last_name": "Freeman",
    "enabled": true,
    "role_id": "59de4bb09221034b071d83db64950d34",
    "created_at": "2016-11-22T00:00:00Z",
    "updated_at": "2016-11-22T01:22:21.421327Z"
}

• id - (string) The ID of the user (auto-generated)
• email - (string) The email (must be unique)
• first_name - (string) user first name
• last_name - (string) user last name
• enabled - (bool) true the account for the user is enabled (default true)
• role_id - (string) The ID of the role assigned to this user
• password - (string) user password (only for creation/ or password change and it will be not stored)
• created_at - (datetime) date and time of the creation (auto-calculated)
• updated_at - (datetime) date and time of the last update (auto-calculated)

Create a User

POST /api/data/users

{
    "email": "ada@graymeta.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "password": "secret1234",
    "role_id": "59de4bb09221034b071d83db64950d34"
}

The response will be 201, with the User object

{
    "id": "583ba3125b9f5421e1cb5702deb8d45e",
    "email": "ada@graymeta.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "enabled": true,
    "role_id": "59de4bb09221034b071d83db64950d34",
    "created_at": "2016-11-28T00:00:00Z",
    "updated_at": "2016-11-28T14:22:58.44874Z"
}

Retrieve the user

GET /api/data/users/{id}

• {id} - (string) the user id

GET /api/data/users/583ba3125b9f5421e1cb5702deb8d45e

Response

{
    "id": "583ba3125b9f5421e1cb5702deb8d45e",
    "email": "ada@graymeta.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "enabled": true,
    "role_id": "59de4bb09221034b071d83db64950d34",
    "created_at": "2016-11-28T00:00:00Z",
    "updated_at": "2016-11-28T14:22:58.44874Z"
}

Update a User

PUT /api/data/users/{id}

• {id} - (string) the user id

{
    "email": "ada.lovelace@graymeta.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "enabled": false,
    "role_id": "59de4bb09221034b071d83db64950d34"
}

Partial update of User

PATCH /api/data/users/{id}

• {id} - (string) the user id

{
    "admin": false,
    "last_name": "Potter"
}

Update user password

Note: This API can only be used to change the password for the user that is currently logged-in. Administrators cannot use this API to change other users’ passwords.

PUT /api/data/users/{id}/password

• {id} - (string) the user id

{
    "password": "newsecret12345"
}

Retrieve all users

GET /api/data/users

Response

{
    "users": [
        {
            "id": "583ba3125b9f5421e1cb5702deb8d45e",
            "email": "ada@graymeta.com",
            "first_name": "Ada",
            "last_name": "Lovelace",
            "enabled": true,
            "role_id": "59de4bb09221034b071d83db64950d34",
            "created_at": "2016-11-28T00:00:00Z",
            "updated_at": "2016-11-28T14:22:58.44874Z"
        },
        {...},
        {...}
    ]
}

Retrieve users by email

GET /api/data/users?email=ada@graymeta.com

Response

[
    {
        "id": "583ba3125b9f5421e1cb5702deb8d45e",
        "email": "ada@graymeta.com",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "enabled": true,
        "role_id": "59de4bb09221034b071d83db64950d34",
        "created_at": "2016-11-28T00:00:00Z",
        "updated_at": "2016-11-28T14:22:58.44874Z"
    }
]

Users in Groups

You can add/remove users from groups with the following API.

Add a user to a group

PUT /api/data/v3/users/{id}/groups/{group_id}

• {id} - (string) the user id
• {group_id} - (string) the group id

Response in case the group is added

{
    "ok": true
}

Remove a user from group

DELETE /api/data/v3/users/{id}/groups/{group_id}

• {id} - (string) the user id
• {group_id} - (string) the group id

List the groups of a user

GET /api/data/v3/users/{id}/groups

• {id} - (string) the user id

{
    "groups": [
        {
            "id": "ADMIN",
            "name": "Admin"
        },
        {
            "id": "EDITORS",
            "name": "Editors"
        }
    ]
}

Groups

You can create and manage groups with a RESTful interface in the GrayMeta Platform, with the following object and endpoints

Group Object

{
    "id": "EDITORS",
    "name": "Editors",
    "description": "Description of what editors have access to"
}

• id - (string) The ID of the group (auto-calculated based on the name of the group)
• name - (string) Name of the group
• description - (string) Describe what the group is about

Create a Group

POST /api/data/v3/groups

{
    "name": "Editors",
    "description": "Editors can access daily clips"
}

The response will be 201, with the Group object

{
    "id": "EDITORS",
    "name": "Editors",
    "description": "Editors can access daily clips"
}

Update a Group

PUT /api/data/v3/groups/{id}

• id - (string) The ID of the group

For example

PUT /api/data/v3/groups/EDITORS

{
    "name": "Video Editors",
    "description": "My new description"
}

Retrieve a Group

GET /api/data/v3/groups/{id}

• id - (string) The ID of the group

GET /api/data/v3/groups/EDITORS

Response

{
    "id": "EDITORS",
    "name": "Editors",
    "description": "Explanation of this group"
}

Retrieve all Group

GET /api/data/v3/groups

Response

{
    "groups": [
      {
        "id": "ADMIN",
        "name": "Admin",
            "description": "Admins have full access"
      },
      {
        "id": "EDITORS",
        "name": "Editors",
            "description": "Editor can access only daily clips"
      },
        {...}
    ]
}

Delete a Group

DELETE /api/data/v3/groups/{id}

• id - (string) The ID of the group

For example

DELETE /api/data/v3/groups/EDITORS

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.

© 2021 GrayMeta, Inc.