Privileges

Privileges are 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)
Bytemark Cloud used to be called "BigV"—nothing has changed except the name! We’re hiring! Please visit careers.bytemark.co.uk to find out more.