Scyld Cloud Auth Documentation

Roles and Permissions API

A permission is one part of a Scyld Cloud Auth User ACL. Roles are simply groups of permissions.

Roles are made up of the following key-value pairs:

• id - Integer.
• name - String. Descriptive name.
• description - String.
• permissions - List of permissions (see below).

Permissions are made up of the following key-value pairs:

• id - Integer.
• name - String. Permission name.
• description - String.
• object_type - String or none. If the permission is specific to an object_type, it will be listed here.

/role/list

/v{version}/role/list

List all defined roles.

Permissions

manage_role

Request Parameters

None.

Error Codes

• 403 Forbidden - Requester does not have permission.

Response Payload

List of roles.

Sample Output::

{'data': {'roles': [{'id': 1,
                     'name': 'superuser',
                     'description': 'All permissions.',
                     'permissions': []},

                     {'id': 2,
                      'name': 'cloud_controller_admin',
                      'description': 'Ability to manage Scyld Cloud Cluster Controllers.',
                      'permissions': ['create_cc', 'delete_cc', 'manage_cc']}],

          'total': 2},
 'message': '',
 'success': True,
 'version': '1.0'}

/role/view/{role_id}

/v{version}/view/{role_id}

View a single role with its list of users who are members.

Permissions

manage_role

Request Parameters

None.

Error Codes

• 403 Forbidden - Requester does not have permission.
• 404 Not Found - Role does not exist.

Response Payload

A role object, along with a list of users who are members. Each user has the following key-value pairs:

• id: Integer.
• email: String.

Sample Output::

{'data': {'role': {'id': 1,
                   'name': 'superuser',
                   'description': 'All permissions.',
                   'permissions': [],
                   'members': [{'email': 'root@localhost', 'id': 2895}]}},


 'message': '',
 'success': True,
 'version': '1.0'}

/role/add_user/{role_id}

/v{version}/role/add_user/{role_id}

• HTTP POST required.

Adds one or more users to the specified role.

Permissions

manage_role

Request Parameters

• user_id - Integer. Required. Additional user_id values are optional.

Error Codes

• 400 Bad Request - Missing or malformed parameters.
• 403 Forbidden - Requester does not have permission.
• 404 Not Found - Role does not exist.

Response Payload

None. If any errors are encountered, no updates will take place and details will be provided in the ‘error’ parameter in the response.

/role/remove_user/{role_id}

/v{version}/role/remove_user/{role_id}

• HTTP POST required.

Removes one or more users from the specified role.

Permissions

manage_role

Request Parameters

• user_id - Integer. Required. Additional user_id values are optional.

Error Codes

• 400 Bad Request - Missing or malformed parameters.
• 403 Forbidden - Requester does not have permission.
• 404 Not Found - Role does not exist.

Response Payload

None. If any errors are encountered, no updates will take place and details will be provided in the ‘error’ parameter in the response.

/permission/list

/v{version}/list

List all defined permissions.

Permissions

manage_role

Request Parameters

None.

Error Codes

• 403 Forbidden - Requester does not have permission.

Response Payload

List of permissions.

Sample Output::

{'data': {'permissions': [{'id': 13,
                           'name': 'manage_instance',
                           'description': 'Allow all permissions, including delete, on a SCM server instance.',
                            'object_type': 'Instance'},

                          {'id': 10,
                           'name': 'activate_instance',
                           'description': 'Allow reboot, power off/on on a SCM server instance.',
                            'object_type': u'Instance'},

                           {'id': 17,
                            'name': 'auth_query',
                            'description': 'Allow querying of user ACLs. For use by SCM services.',
                            'object_type': None}],
          'total': 3},

 'message': '',
 'success': True,
 'version': '1.0'}

/permission/view/{permission_id} or /permission/view/{permission}

/v{version}/permission/view/{permission_id} or /v{version}/permission/view/{permission}

View a single permission along with a list of ACLs that include this permission.

Permissions

manage_role

Request Parameters

None.

Error Codes

• 403 Forbidden - Requester does not have permission.
• 404 Not Found - Permission does not exist.

Response Payload

A permission object, along with a list of ACLs that include this permission. Each ACL has the following key-value pairs:

• object_id - String. Specific resource instance reference, or ‘ALL’.
• user - A list of users, each with the following key-value pairs:
  • • id: Integer. Userid.
  • • email: String. User account email.

Sample Output::

{'data': {'permission': {'id': 12,
                         'name': 'access_instance',
                         'description': 'Allow login to server instance.',
                         'object_type': 'Instance',
                         'acls': [{'object_id': '8b0335cc14ce4aada04221dfa14c63ac',
                                   'user': {'email': 'jdoe@gmail.com',
                                            'id': 160}},
                                  {'object_id': '8b0335cc14ce4aada04221dfa14c63ac',
                                   'user': {'email': 'janesmith@gmail.com',
                                            'id': 2}}]}},

 'message': '',
 'success': True,
 'version': '1.0'}

/acl/list/{object_type}/{object_id}

/v{version}/acl/list/{object_type}/{object_id}

List all ACL entries for a particular resource object.

Permissions

auth_query

Request Parameters

None.

Error Codes

• 403 Forbidden - Requester does not have permission.

Response Payload

List of ACL entries. Each acl entry has the following key-value pairs:

• object-type - String.
• object_id - String.
• user - A key-value pair of:
  • id - Integer. Userid.
  • Email - String. Email address of user account.
• permission_id - Integer.
• permission - String.

Sample Output::

{'data': {'acls': [{'object_id': '8b0335cc14ce4aada04221dfa14c63ac',
                    'object_type': 'Instance',
                    'permission': 'access_instance',
                    'permission_id': 12,
                    'user': {'email': 'jdoe@gmail.com', 'id': 160}},
                    {'object_id': '8b0335cc14ce4aada04221dfa14c63ac',
                     'object_type': 'Instance',
                     'permission': 'access_instance',
                     'permission_id': 12,
                     'user': {'email': 'janesmith@gmail.com', 'id': 2}}],

          'total': 2},
 'message': '',
 'success': True,
 'version': '1.0'}