Scyld Cloud Auth Documentation

User API

The methods that return data about and modify Scyld Cloud user accounts are listed below. In general, a user can view and modify their own records and those of any users he/she owns.

User Object

A Scyld Cloud user object (singly or in a list) that is returned by relevant User API calls will contain the following fields:

  • id: String uuid.
  • email: String.
  • name: String.
  • password: String.
  • active: Integer. Any value greater than zero indicates an active account.
  • owner_userid: String uuid, reference to a User.id. If present, the value indicates the id of the user responsible for this account.
  • system_accounts: List of system accounts. Each system account has the following key-value pairs:
    • id: Integer.
    • username: String.
    • uuid: String. Scyld Cloud Controller id.
    • cloud_controller_id: Integer. Id of the instance of Scyld Cloud Controller. Reference to cloud_controller.id.

In addition, the following fields are included if the requester is a superuser.

  • api_key: String.
  • num_owned_accounts: Integer.
  • roles: List of strings.
  • registration_source: String.

/user/list

/v{version}/user/list

Returns a list of user records. If the request is made by a superuser, all users are returned or only those specified by an optional owner_userid parameter. If the request is not made by a superuser, only users that are owned by the requester or that the user has explicit view permission are returned. Only active users are returned unless specified.

Permissions

view_user for users returned.

Request Parameters

  • owner_userid - Optional, superuser only. Limits list of users returned to those owned by a particular user.
  • show_inactive - Optional, superuser only. If present, include inactive users in response.
  • registration_source - Optional, superuser only. String. Filter list of users returned to a specific value for registration_source.

Response Payload

  • total - Integer. Number of users returned.
  • users - List of user objects.

Sample output:

{'data': {'total': 2,
          'users': [{'id': '69a70cbc860c4db391acbe06dcc224f7',
                     'owner_userid': 'cd32807f6913466e89d1aabcb3a40682',
                     'email': 'jdoe@gmail.com',
                     'name': 'John Doe'
                     'active': 1,
                     'created_at_utc': '2013-03-09T00:00:00Z',
                     'system_accounts': [{'id': 8,
                                          'cloud_controller_id': 5,
                                          'uuid': '39a925934cc04f7dbafe8dd121ac2bcf',
                                          'username': 'jdoe'}]},

                    {'id': 'c36666acb7e14d4d8d11ff55e2a621ab',
                     'owner_userid': 'cd32807f6913466e89d1aabcb3a40682',
                     'email': 'test9005@gmail.com',
                     'name': 'Jane Johnson',
                     'active': 1,
                     'created_at_utc': '2012-06-06T18:58:57Z',
                     'system_accounts': [{'id': 9,
                                          'cloud_controller_id': 5,
                                          'uuid': 'e2c9bbdca0544e509713ac492e29dea2',
                                          'username': 'test9005'}]}]},
'message': '',
'success': True,
'version': '1.0'}

/user/view/{userid}

/v{version}/user/view/{userid}

This call returns a single user object.

Permissions

view_user for this user.

Request Parameters

None.

Error Codes

  • 403 Forbidden - Requester does not have view permissions on this user.
  • 404 Not Found - Userid does not exist.

Response Payload

  • user - A User object.

Sample output:

{'data': {'user': {'id': '6002b5e125244b48b8f7712c1b9bbcc7',
                   'owner_userid': 0,
                   'email': 'demo@penguincomputing.com',
                   'name': 'Jane Doe',
                   'active': 1,
                   'system_accounts': [{'id': 8,
                                        'cloud_controller_id': 5,
                                        'uuid': '29c46b32f8c24c889d1d3aa6de79a952',
                                        'username': 'demotest08'}]}},
'message': '',
'success': True,
'version': '1.0'}

/user/create

/v{version}/user/create

  • HTTP POST required.

This method creates a Scyld Cloud Auth user account.

Permissions

create_user

Request Parameters .. _password_requirements:

  • email: Required. String. A valid email address.
  • password: Required. String. Passwords are required to be 14-24 characters in length and include characters from at least 2 out of the following 3 character classes: a) letters b) numbers, and c) punctuation.
  • owner_userid: Optional. String uuid. If specified, this user account will be created as a managed user.
  • active: Optional. Integer. Defaults to 1.
  • registration_source: Optional. String.

Error Codes

Response Payload

  • userid: String uuid. The user.id of the newly created user.

Sample output:

{'data': {'userid': 'df1d4d1c007f4cd7894e33dd7b471508'},
 'message': '',
 'success': True,
 'version': '1.0'}

/user/update/{userid}

/v{version}/user/update/{userid}

Updates the properties of a user record. Generally used by the superuser only.

  • HTTP POST required.

Permissions

update_user

Request Parameters

Specify which user properties to update by including them in the request parameters.

  • email: String. A valid email address.
  • active: Integer. A zero indicates a inactive account; a value greater than zero indicates an active account. Superuser only.

Error Codes

  • 403 Forbidden - Requester does not have update permissions on this user.
  • 404 Not Found - Userid does not exist.

Response Payload

None.

Sample output:

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

/user/search

/v{version}/user/search

If a userid is not known, this method can be used to locate a Scyld Cloud user based on their email address or system username. Email address must be an exact string match and the return list will contain only a single user if a match is found. System account usernames must be an exact match and all matching users will be returned.

Permissions

view_user for users returned.

Request Parameters

  • email: Optional. String.
  • username: Optional. String.

Either email or username must be included.

Error Codes

Response

  • users - List of user objects, or an empty list if no match is found.

Sample output:

{'data': {'total': 1,
          'users': [{'id': 277,
                     'owner_userid': 0,
                     'email': 'jdoe@gmail.com',
                     'email': 'John Doe',
                     'active': 1,
                     'created_at_utc': '2012-02-09T00:03:50Z',
                     'system_accounts': [{'id': 8,
                                          'cloud_controller_id': 5,
                                          'uuid': '29c46b32f8c24c889d1d3aa6de79a952',
                                          'username': 'demotest08'}]}]},
'message': '',
'success': True,
'version': '1.0'}

/user/set_password/{userid}

/v{version}/user/set_password/{userid}

  • HTTP POST required.

Used by the superuser only to set a new user password.

Permissions

superuser only

Request Parameters

  • password: Required.

Error Codes

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

Response Payload

None

/user/view_api_secret/{userid}

/v{version}/user/view_api_secret/{userid}

Used by the superuser to view a user’s API secret.

Permissions

superuser or view_user_secret

Request Parameters

None

Error Codes

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

Response Payload

api_secret: String.

/user/reset_api_secret/{userid}

/v{version}/user/reset_api_secret/{userid}

  • HTTP POST required.

Used by the superuser only to reset a user’s API secret. Users must use a Scyld Cloud Portal to maintain their API key and secret.

Permissions

superuser only

Request Parameters

  • set_to_null: Optional. If this parameter is present, the user’s API secret will be set to null, effectively revoking the secret and making the user unable to use the Scyld Cloud APIs.

Error Codes

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

Response Payload

api_secret: String.

/user/delete/{email}

/v{version}/user/delete/{email}

  • HTTP POST required.

Only users that have not been enabled can be deleted.

Permissions

superuser only

Request Parameters

None

Error Codes

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

Response Payload

None





Scyld Cloud Auth

SCM API Documentation