ACLs (Access Control Lists)

Access Control Lists (ACLs) can be used to grant permissions to another user to manage your resources. For example it is possible to permit another user to start or stop your servers or to allow another user to connect their servers to your private network (VLAN).

Permissions can be granted on servers, drives, network resources, and firewall policies. All of these resources support LIST and EDIT permissions, which respectively allow the grantee to see the resources when listing them and to edit resources. When a user is granted a LIST permission, this resource appears in the grantee’s resource list. For example granting LIST on a drive will make it appear in the list with grantees drives, when they make a GET request to /drives. Own resources can be differentiated from granted resources, by the owner field.

Some resources have additional permissions. Drives have ATTACH permission which allows another user to use the drive on their server. IPs, VLANs, and Firewall policies have ATTACH which will allow another user to assign these network resource to NICs on their server. Servers have START and STOP, OPEN_VNC permissions which allow another user to start or stop the server, or to open the server console through VNC. Note that ACLs may contain permissions that are not directly applicable on some resources, for example it is possible to to have STOP permission in an ACL on tag which refers only to drives. Drives and servers support CLONE permission, which allows cloning them to the grantee account. Note that in order to clone someone else’s server, you need CLONE permission on both the owner’s server, and on the attached non-cdrom drives. For cdrom drives, the user will need a ATTACH permission. The table below summarizes the permissions applicable to each resource:

Resource Permissions
Server LIST EDIT CLONE START STOP OPEN_VNC
Drive LIST EDIT CLONE ATTACH
IP, VLAN, Firewall Policy LIST EDIT ATTACH

ACLs are granted on tags, and apply for all the tagged resources. One ACL can be attached to multiple tags, and will apply to the set of all resources tagged by these tags. It is also possible to have multiple ACLs on a tag, in which case the permissions on the tagged resources are the combination of all ACLs rules.

Each ACL can have one or more grantee users. Each ACL object has a list of rules, which specify what permission are given by the ACL.

Permissions are not transferable to third parties, i.e. if you grant permission to someone, they can’t grant it to a third user. Only owners can grant permissions.

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616#section-9 for more details on HTTP methods semantics

Listing

GET /acls/

Gets the list of ACLs defined by the authenticated user.

statuscode 200:no error

Example request:

GET /api/2.0/acls/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 3
    },
    "objects": [
        {
            "grantees": [
                {
                    "email": "user2@example.com",
                    "resource_uri": {
                        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
                    },
                    "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
                }
            ],
            "meta": {},
            "name": "shared_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "resource_uri": "/api/2.0/acls/d29837e8-27ea-46e8-8b46-843d0df50a82/",
            "rules": [
                {
                    "permission": "ATTACH"
                },
                {
                    "permission": "OPEN_VNC"
                },
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                },
                {
                    "permission": "DELETE"
                },
                {
                    "permission": "START"
                },
                {
                    "permission": "STOP"
                },
                {
                    "permission": "CLONE"
                }
            ],
            "tags": [],
            "uuid": "d29837e8-27ea-46e8-8b46-843d0df50a82"
        },
        {
            "grantees": [
                {
                    "email": "user2@example.com",
                    "resource_uri": {
                        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
                    },
                    "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
                }
            ],
            "meta": {},
            "name": "shared_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "resource_uri": "/api/2.0/acls/58aa5d82-e890-44db-8cb8-fe3a2f159320/",
            "rules": [
                {
                    "permission": "ATTACH"
                },
                {
                    "permission": "OPEN_VNC"
                },
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                },
                {
                    "permission": "DELETE"
                },
                {
                    "permission": "START"
                },
                {
                    "permission": "STOP"
                },
                {
                    "permission": "CLONE"
                }
            ],
            "tags": [],
            "uuid": "58aa5d82-e890-44db-8cb8-fe3a2f159320"
        },
        {
            "grantees": [],
            "meta": {},
            "name": "test_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
            "rules": [],
            "tags": [],
            "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
        }
    ]
}

List Single ACL

GET /acls/(uuid: acl_uuid)/

Gets detailed information for an ACL identified by acl_uuid.

statuscode 200:no error

Example request:

GET /api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "grantees": [
        {
            "email": "user@example.com",
            "resource_uri": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
        }
    ],
    "meta": {},
    "name": "test_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
    "rules": [
        {
            "permission": "LIST"
        },
        {
            "permission": "EDIT"
        }
    ],
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        },
        {
            "resource_uri": "/api/2.0/tags/5a9e6f2b-7927-4f30-88b5-0cc939208549/",
            "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
        }
    ],
    "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
}

Creating

POST /acls/

Creates a new ACL.

statuscode 201:object created

Example request:

POST /api/2.0/acls/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "grantees": [],
            "name": "test_acl",
            "rules": [],
            "tags": []
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "grantees": [],
            "meta": {},
            "name": "test_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
            "rules": [],
            "tags": [],
            "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
        }
    ]
}

It is possible to define the grantees, tags and rules at creation time. Just specify their UUIDs the grantees list:

Example request:

POST /api/2.0/acls/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "grantees": [
                {
                    "email": "user@example.com",
                    "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                }
            ],
            "name": "test_with_grantees",
            "rules": [
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                }
            ],
            "tags": [
                {
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                },
                {
                    "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
                }
            ]
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "grantees": [
                {
                    "email": "user@example.com",
                    "resource_uri": {
                        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                    },
                    "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                }
            ],
            "meta": {},
            "name": "test_with_grantees",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/acls/49134280-55ed-4f4e-815c-85c6dd3ab322/",
            "rules": [
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                }
            ],
            "tags": [
                {
                    "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                },
                {
                    "resource_uri": "/api/2.0/tags/5a9e6f2b-7927-4f30-88b5-0cc939208549/",
                    "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
                }
            ],
            "uuid": "49134280-55ed-4f4e-815c-85c6dd3ab322"
        }
    ]
}

Editing

PUT /acls/{uuid}/

Edits an ACL.

statuscode 200:no error

Example request:

PUT /api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "grantees": [
        {
            "email": "user@example.com",
            "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
        }
    ],
    "meta": {},
    "name": "test_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
    "rules": [
        {
            "permission": "LIST"
        },
        {
            "permission": "EDIT"
        }
    ],
    "tags": [
        {
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        },
        {
            "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
        }
    ],
    "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "grantees": [
        {
            "email": "user@example.com",
            "resource_uri": {
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            },
            "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
        }
    ],
    "meta": {},
    "name": "test_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "resource_uri": "/api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/",
    "rules": [
        {
            "permission": "LIST"
        },
        {
            "permission": "EDIT"
        }
    ],
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        },
        {
            "resource_uri": "/api/2.0/tags/5a9e6f2b-7927-4f30-88b5-0cc939208549/",
            "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
        }
    ],
    "uuid": "adf048e8-5445-47cf-a09c-fc3cfb2c823f"
}

Deleting

DELETE /acls/{uuid}/

Deletes a single ACL.

statuscode 204:No content, object deletion started.

Example request:

DELETE /api/2.0/acls/adf048e8-5445-47cf-a09c-fc3cfb2c823f/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Full Example of Sharing a Resource

First let’s create a tag which will be shared with another user:

Request:

POST /api/2.0/tags/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "test_TagOne"
        }
    ]
}

Response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "test_TagOne",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "resources": [],
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        }
    ]
}

Let’s create a drive tagged with the new tag:

Request:

POST /api/2.0/drives/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "media": "disk",
            "name": "test_drive_acl",
            "size": 2147483648,
            "tags": [
                "6d302107-fc0b-433a-99b1-9f2d3692eefc"
            ]
        }
    ]
}

Response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "affinities": [],
            "allow_multimount": false,
            "grantees": [],
            "jobs": [],
            "licenses": [],
            "media": "disk",
            "meta": {},
            "mounted_on": [],
            "name": "test_drive_acl",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "permissions": [],
            "resource_uri": "/api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/",
            "runtime": {
                "is_snapshotable": true,
                "snapshots_allocated_size": 0,
                "storage_type": "dssd"
            },
            "size": 2147483648,
            "snapshots": [],
            "status": "creating",
            "storage_type": "dssd",
            "tags": [
                {
                    "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                }
            ],
            "uuid": "ac5ca635-d119-4dda-b27a-fa5a69fc17da"
        }
    ]
}

It is also possible to tag an existing drive. Since there is no ACL on the tag, the grantees attribute of the drive is empty.

Now let’s add the tag to an ACL. Notice that we may add several tags to the ACL:

Request:

POST /api/2.0/acls/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "grantees": [
                {
                    "email": "user@example.com",
                    "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                }
            ],
            "name": "test_with_grantees",
            "rules": [
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                }
            ],
            "tags": [
                {
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                },
                {
                    "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
                }
            ]
        }
    ]
}

Response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "grantees": [
                {
                    "email": "user@example.com",
                    "resource_uri": {
                        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                    },
                    "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                }
            ],
            "meta": {},
            "name": "test_with_grantees",
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "resource_uri": "/api/2.0/acls/49134280-55ed-4f4e-815c-85c6dd3ab322/",
            "rules": [
                {
                    "permission": "LIST"
                },
                {
                    "permission": "EDIT"
                }
            ],
            "tags": [
                {
                    "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                },
                {
                    "resource_uri": "/api/2.0/tags/5a9e6f2b-7927-4f30-88b5-0cc939208549/",
                    "uuid": "5a9e6f2b-7927-4f30-88b5-0cc939208549"
                }
            ],
            "uuid": "49134280-55ed-4f4e-815c-85c6dd3ab322"
        }
    ]
}

If we get the drive definition we will see the grantee in the grantees attribute:

GET /api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [
        {
            "permissions": [
                "EDIT",
                "LIST"
            ],
            "user": {
                "email": null,
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            }
        }
    ],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 2147483648,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        }
    ],
    "uuid": "ac5ca635-d119-4dda-b27a-fa5a69fc17da"
}

Since there is an ACL on the the tag all resources created with this tag will be shared. For example if we create a server with the same tag, we see that it also shows grantees:

POST /api/2.0/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "cpu": 1000,
            "mem": 536870912,
            "name": "test_server",
            "tags": [
                "6d302107-fc0b-433a-99b1-9f2d3692eefc"
            ],
            "vnc_password": "pass"
        }
    ]
}
HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "context": true,
            "cpu": 1000,
            "cpu_model": null,
            "cpu_type": "amd",
            "cpus_instead_of_cores": false,
            "drives": [],
            "enable_numa": false,
            "grantees": [
                {
                    "permissions": [
                        "EDIT",
                        "LIST"
                    ],
                    "user": {
                        "email": "user@example.com",
                        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
                    }
                }
            ],
            "hv_relaxed": false,
            "hv_tsc": false,
            "hypervisor": "kvm",
            "jobs": [],
            "mem": 536870912,
            "meta": {},
            "name": "test_server",
            "nics": [],
            "owner": {
                "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
                "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
            },
            "permissions": [],
            "pubkeys": [],
            "requirements": [],
            "resource_uri": "/api/2.0/servers/e97f8858-4c59-476f-b7e6-08ec2ec85582/",
            "runtime": null,
            "smp": 1,
            "status": "stopped",
            "tags": [
                {
                    "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
                    "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
                }
            ],
            "uuid": "e97f8858-4c59-476f-b7e6-08ec2ec85582",
            "vnc_password": "pass"
        }
    ]
}

Permissions on Resources Attached to a Server

When updating another user’s server, the attached resources, such as drives, IPs, VLANs, or firewall policies, should be available for the server owner. This means that either the attached resource should be owned by the server owner, or the owner should be given ATTACH permission on the attached resource. For example if user A shares a server with EDIT permission to user B, and user B wants to attach their drive on the server, user B will have to grant ATTACH permission on the drive, so that the owner of the server is able to start it. Trying to attach a drive, on which there is no permission for the owner of the server will result in an error.

Recognizing Shared Resources and What Permissions Are Given on Them

Finding out which resources were shared with you

Resources shared with you appear in the resource list along with your own resources. In order to differentiate between owner, and shared with you resources you have to look at the owner field. If the user is the same as you, the resource is yours. Non-owned resource have their respective owner uuid in the owner field. The examples in the next two subsections show the same drive from the view point of permission grantor and grantee. Notice how owner is the same.

Finding what permissions are granted to you on a resource

While it is possible to follow the ACL-tag-resource graph to find out what are the resulting permissions on a resource, it hard to do so in a simple script. That is why each resource has permissions field, which shows the effective permissions the current user has on the resource. The permissions field is empty if the owner is the same as the current user.

For example if you get the definition of a drive shared by another user with you:

GET /api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "permissions": [
        "EDIT",
        "LIST"
    ],
    "resource_uri": "/api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 2147483648,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [],
    "uuid": "ac5ca635-d119-4dda-b27a-fa5a69fc17da"
}

The definition includes non-empty permissions attribute:

{
    "permissions": [
        "EDIT",
        "LIST"
    ]
}

In the next subsection there is an example of the same drive but from the view point of the drive owner.

Finding what permissions you have granted on a resource

As is the case with finding out what permissions are given to the current user, it also hard to find out, to find out what is granted to other users, as users may be granted different permissions through several ACLs referring to different tags. Therefore each resource has read-only field grantees. Each object of the grantees list contains a references to the grantee user, and a list of the permissions granted to them.

For example if you get the definition of your drive shared with another user:

GET /api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "affinities": [],
    "allow_multimount": false,
    "grantees": [
        {
            "permissions": [
                "EDIT",
                "LIST"
            ],
            "user": {
                "email": null,
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            }
        }
    ],
    "jobs": [],
    "licenses": [],
    "media": "disk",
    "meta": {},
    "mounted_on": [],
    "name": "test_drive_acl",
    "owner": {
        "resource_uri": "/api/2.0/user/3516e556-eb0e-4f0c-bf95-8b642194b8fd/",
        "uuid": "3516e556-eb0e-4f0c-bf95-8b642194b8fd"
    },
    "permissions": [],
    "resource_uri": "/api/2.0/drives/ac5ca635-d119-4dda-b27a-fa5a69fc17da/",
    "runtime": {
        "is_snapshotable": true,
        "snapshots_allocated_size": 0,
        "storage_type": "dssd"
    },
    "size": 2147483648,
    "snapshots": [],
    "status": "unmounted",
    "storage_type": "dssd",
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6d302107-fc0b-433a-99b1-9f2d3692eefc/",
            "uuid": "6d302107-fc0b-433a-99b1-9f2d3692eefc"
        }
    ],
    "uuid": "ac5ca635-d119-4dda-b27a-fa5a69fc17da"
}

The definition includes non-empty grantees attribute:

{
    "grantees": [
        {
            "permissions": [
                "EDIT",
                "LIST"
            ],
            "user": {
                "email": null,
                "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
                "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
            }
        }
    ]
}

In the previous subsection there is an example of the same drive definition but from the view point of the permissions grantee.

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "post",
        "delete"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "grantees": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "nullable": true,
            "readonly": false,
            "type": "related",
            "unique": false
        },
        "meta": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "A dictionary of data. Ex: {'price': 26.73, 'name': 'Daniel'}",
            "nullable": false,
            "readonly": false,
            "type": "dict",
            "unique": false
        },
        "name": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "owner": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "A single related resource. Can be either a URI or set of nested resource data.",
            "nullable": false,
            "readonly": true,
            "type": "related",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "rules": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "ACL rules",
            "nullable": true,
            "readonly": false,
            "type": "related",
            "unique": false
        },
        "tags": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "nullable": true,
            "readonly": false,
            "type": "related",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        }
    }
}