Privileges

Privileges allow you to map users to accounts, groups or even individual virtual machines. This API allows you to allocate fine-grained access control to new users.

Endpoints

These are all relative to https://uk0.bigv.io

GET    /privileges
GET    /privileges/{privilege-id}
PUT    /privileges/{privilege-id}
DELETE /privileges/{privilege-id}

POST   /users/{user-id}/privileges
GET    /users/{user-id}/privileges

# Non-nested endpoints (currently only GET)
GET    /privileges?user_id={user-id}

• Replace {user-id} with a user id or username.
• Replace {privilege-id} with the id of the privilege.

Attributes

• id – unique key (integer).
• username – username this privilege is for.
• level – the level of privilege (see below).
• creating_username – username of the user who created this user.
• yubikey_required – boolean specifying whether a yubikey is required for access.
• yubikey_otp_max_age – how long the yubikey value will be accepted for (in seconds).
• ip_restrictions – whether the user has to be accessing from certain IP addresses to have this privilege.

And one of the following:

• virtual_machine_id
• group_id
• account_id

The valid levels are:

• account_admin
• group_admin
• vm_admin
• vm_console

Users can only create or modify privileges which have a lower level than themselves (e.g., an account_admin cannot DELETE another user’s account_admin privileges.

Once created, only yubikey_required, yubikey_otp_max_age and ip_restrictions can be updated.

Examples

All Privileges for your user

Request

GET /privileges

Curl:

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     https://uk0.bigv.io/privileges

Response (success: 200)

[  
  {  
    "id":1,
    "level":"account_admin",
    "yubikey_required":true,
    "yubikey_otp_max_age":900,
    "ip_restrictions":null,
    "username":"myusername",
    "_links":{  
      "self":{  
        "href":"/privileges/25"
      },
      "user":{  
        "href":"/users/25"
      },
      "account":{  
        "href":"/accounts/24",
        "title":"Account myaccountname"
      }
    },
    "account_id":1
  }
]

Single Privilege

Request

GET /privileges/{privilege-id}

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     https://uk0.bigv.io/privileges/1

Response (success: 200):

{"id":1,"level":"account_admin","yubikey_required":true,"yubikey_otp_max_age":900,"ip_restrictions":null,"username":"myusername","_links":{"self":{"href":"/privileges/25"},"user":{"href":"/users/25"},"account":{"href":"/accounts/24","title":"Account myaccountname"}},"account_id":1},{"id":5273,"level":"account_admin","yubikey_required":true,"yubikey_otp_max_age":900,"ip_restrictions":null,"username":"myusername","_links":{"self":{"href":"/privileges/5273"},"user":{"href":"/users/25"},"account":{"href":"/accounts/5114","title":"Account myotheraccount"}},"account_id":2}

Create Privilege

Request

POST /users/{user-id}/privileges

Curl:

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -X POST \
     -d '{"level":"vm_admin", "yubikey_required":false, "virtual_machine_id":45}' \
     https://uk0.bigv.io/users/mynewusername/privileges/1

Response (success: 200)

{"id":6,"level":"vm_admin","yubikey_required":false,"yubikey_otp_max_age":null,"ip_restrictions":null,"username":"mynewusername","_links":{"self":{"href":"/privileges/6"},"user":{"href":"/users/3"},"creating_user":{"href":"/users/3"},"virtual_machine":{"href":"/accounts/3/groups/3/virtual_machines/45","title":"VM myserver1.default.myaccountname.uk0.bigv.io"}},"creating_username":"myusername","virtual_machine_id":45}

Update Privilege

Request

GET /privileges/{privilege-id}

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -d '{"yubikey_required":false}' \
     https://uk0.bigv.io/privileges/6

Response (success: 200):

{"id":6,"level":"vm_admin","yubikey_required":false,"yubikey_otp_max_age":600,"ip_restrictions":null,"username":"mynewusername","_links":{"self":{"href":"/privileges/6"},"user":{"href":"/users/3"},"creating_user":{"href":"/users/3"},"virtual_machine":{"href":"/accounts/3/groups/3/virtual_machines/45","title":"VM myserver1.default.myaccountname.uk0.bigv.io"}},"creating_username":"myusername","virtual_machine_id":45}

Delete Privilege

Request

DELETE /privileges/{privilege-id}

Curl

curl -H "Content-type: application/json" \
     -H "Authorization: Bearer {session-id}" \
     -X DELETE \
     https://uk0.bigv.io/privileges/1

Response (success: 204)