​
API Endpoints and Permission Categories

This document outlines the various API endpoints and their associated permission categories, providing a clear reference for understanding the access control within our system.
Note: In the early days we are going to describe these concepts as things like ‘instance_read’ or ‘instance_write’, We realize these are confusing. Any questions about what permissions are attributed to what actions should be asked via our support channels.
Every API Key has a list of permissions associated with it. Every user has the ability to create keys with restricted permissions on their own account. Users can also create restricted keys in team environments using the team-centric endpoints.

​
Creating Custom Roles

  • Accessing Role Management: Custom roles can be created and managed through the CLI. Team roles can be managed on the ‘Manage’ page by users with team_read level access.
  • Defining Permissions: When creating a custom role, anyone can select from a wide range of permissions, such as instance creation, billing access, monitoring, etc. This allows for precise control over what each role can and cannot do.
  • Assigning Custom Roles: Once a custom role is created, it can be assigned to team members through the team management interface.

​
Important Elements

  • constraints: Constraints can be added at different levels to enforce certain parameters of the body to be specific values
  • params: You can use wildcards to represent placeholder values. (Useful if you want to generate many keys all doing similar operations)

​
Examples

The following json would create a user that has access to the specified categories. In this instance, someone with these permissions would be able to create an instance as well as access billing information
Text
{
    "api": {
        "misc": {}, 
        "user_read":{}, 
        "instance_read": {}, 
        "instance_write": {},
		"billing_read": {},
		"billing_write": {}
    }
}
The following json would create restricted access to only the presented categories. In this example, someone with these permissions would be able to create an instance, but they would not be able to access billing information
Text
{
    "api": {
        "misc": {}, 
        "user_read":{}, 
        "instance_read": {}, 
        "instance_write": {}
    }
}
You can see a full list of permission types as well as the endpoints attached to that permission below

​
Permission Categories

​
instance_read

The following permissions would allow a user to read the instance logs of instance id 1227 only
Text
{
    "api": {
        "misc": {}, 
        "user_read":{}, 
        "instance_read": {}, 
        "instance_write": {},
        "billing_read": {
            "api.instance.request_logs": {
                "constraints": {
                    "id": {
                        "eq": 1227
                    }
                }
            }
        }
    }
}
The following permissions would allow a user to read the instance logs of instance id from 1to1 to 2. Apikeys using this feature have to be created using the CLI call create api-key
Text
{
    "api": {
        "instance_read": {
            "api.instance.request_logs": {
                "constraints": {
                    "id": {
                        "lte": $1,
                        "gte": $2
                    }
                }
            }
        }
    }
}

​
instance_write

{
	"api": {
        "instance_write": {}
    }
}

​
user_read

Text
{
	"api": {
        "user_read": {}
    }
}

​
user_write

Text
{
	"api": {
        "user_write": {}
    }
}

​
billing_read

Text
{
	"api": {
        "billing_read": {}
    }
}

​
billing_write

Text
{
	"api": {
        "billing_write": {}
    }
}

​
machine_read

Text
{
	"api": {
        "machine_read": {}
    }
}

​
machine_write

{
	"api": {
        "machine_write": {}
    }
}

​
misc

Text
{
	"api": {
        "misc": {}
    }
}

​
team_read

Text
{
	"api": {
        "team_read": {}
    }
}

​
team_write

JSON
{
	"api": {
        "team_write": {}
    }
}