Manage Your Fleet with Viam's Cloud API

The cloud app API allows you to manage your machine fleet with code instead of with the graphical interface of the Viam app. With it you can

  • create and manage organizations, locations, and individual machines
  • manage permissions and authorization
  • create and manage fragments

Establish a connection

To use the Viam cloud app API, you first need to instantiate a ViamClient and then instantiate an AppClient. See the following example for reference.

Use the Viam CLI to generate an API key to authenticate.

import asyncio

from viam.rpc.dial import DialOptions, Credentials
from viam.app.viam_client import ViamClient


async def connect() -> ViamClient:
    dial_options = DialOptions(
      credentials=Credentials(
        type="api-key",
        # Replace "<API-KEY>" (including brackets) with your API key
        payload='<API-KEY>',
      ),
      # Replace "<API-KEY-ID>" (including brackets) with your API key
      # ID
      auth_entity='<API-KEY-ID>'
    )
    return await ViamClient.create_from_dial_options(dial_options)


async def main():

    # Make a ViamClient
    viam_client = await connect()
    # Instantiate an AppClient called "cloud" to run cloud app API methods on
    cloud = viam_client.app_client

    viam_client.close()

if __name__ == '__main__':
    asyncio.run(main())

Once you have instantiated an AppClient, you can run the following API methods against the AppClient object (named cloud in the examples).

API

The cloud API supports the following methods (among others):

Method NameDescription
ListOrganizationsList the organizations the user owns.
GetOrganizationNamespaceAvailabilityCheck the availability of an organization namespace.
ListOrganizationMembersList the members and invites of the current organization.
UpdateOrganizationInviteAuthorizationsUpdate the authorizations attached to an organization invite that has already been created.
CreateLocationCreate and name a location.
GetLocationGet a location by its ID.
UpdateLocationChange the name of and/or assign a parent location to a location.
DeleteLocationDelete a location.
ListLocationsList locations.
LocationAuthGet a location’s authorization (location secrets).
CreateLocationSecretCreate a new location secret. Deprecated.
DeleteLocationSecretDelete a location secret. Deprecated.
GetRobotGet a machine by machine ID.
GetRobotPartsGet a list of all the parts under a specific machine.
GetRobotPartGet a machine part.
GetRobotPartLogsGet the logs associated with a machine part.
TailRobotPartLogsGet an asynchronous iterator that receives live machine part logs.
GetRobotPartHistoryGet a list containing the history of a machine part.
UpdateRobotPartUpdate the name or configuration of a machine part.
NewRobotPartCreate a new machine part.
DeleteRobotPartDelete a machine part.
MarkPartAsMainMark a part as the main part of a machine.
MarkPartForRestartMark a machine part for restart.
CreateRobotPartSecretCreate a machine part secret. Deprecated.
DeleteRobotPartSecretDelete a machine part secret. Deprecated.
ListRobotsGet a list of all machines in a location.
NewRobotCreate a new machine.
UpdateRobotChange the name of an existing machine.
DeleteRobotDelete a machine.
ListFragmentsGet a list of fragments.
GetFragmentGet a fragment by its ID.
CreateFragmentCreate a new private fragment.
UpdateFragmentUpdate a fragment name, config or visibility.
DeleteFragmentDelete a fragment.
AddRoleAdd a role (owner or operator).
RemoveRoleRemove a role (owner or operator).
ListAuthorizationsList authorizations (owners and operators).
CreateModuleCreate a module.
UpdateModuleUpdate module metadata.
UploadModuleFileUpload a module file.
GetModuleGet a module by its ID.
ListModulesList available modules.
CreateOrganizationInviteCreate an organization invite and send it by email.
DeleteOrganizationMemberRemove a member from the organization.
DeleteOrganizationInviteDelete a pending organization invite.
ResendOrganizationInviteResend a pending organization invite email.
GetRoverRentalRobotsReturn a list of rover rental robots within an org.
CheckPermissionsCheck if the entity you’re currently authenticated to is permitted to perform some action or set of actions on the resource you pass to the method.
CreateKeyCreate a new API key.
CreateKeyFromExistingKeyAuthorizationsCreate a new API key with an existing key’s authorizations.
ListKeysList all keys for an organization.

ListOrganizations

List the organizations the user is an authorized user of.

Parameters:

  • None

Returns:

org_list = await cloud.list_organizations()

For more information, see the Python SDK Docs.

ListOrganizationMembers

List the members and invites of the organization that you are currently authenticated to.

Parameters:

  • None

Returns:

member_list, invite_list = await cloud.list_organization_members()

For more information, see the Python SDK Docs.

GetOrganizationNamespaceAvailability

Check the availability of an organization namespace.

Parameters:

  • public_namespace (string): The organization namespace to check. Namespaces can only contain lowercase alphanumeric and dash characters.

Raises:

  • GRPCError: This error is raised if an invalid namespace (for example, "") is provided.

Returns:

  • (bool): True if the provided namespace is available.
available = await cloud.get_organization_namespace_availability(
    public_namespace="my-cool-organization")

For more information, see the Python SDK Docs.

UpdateOrganizationInviteAuthorizations

Update (add or remove) the authorizations attached to an organization invite that has already been created. If an invitation has only one authorization and you want to remove it, delete the invitation instead of using this method.

Parameters:

Raises:

  • GRPCError: This error is raised if no authorizations are passed or if an invalid combination of authorizations is passed (for example, an authorization to remove when the invite only contains one authorization).

Returns:

from viam.proto.app import Authorization

authorization_to_add = Authorization(
    authorization_type="some type of auth",
    authorization_id="identifier",
    resource_type="abc",
    resource_id="resource-identifier123",
    identity_id="id12345",
    organization_id="org_id_123"
)

update_invite = await cloud.update_organization_invite_authorizations(
    email="notarealemail@viam.com",
    remove_authorizations=[authorization_to_add]
)

For more information, see the Python SDK Docs.

CreateLocation

Create and name a location under the organization you are currently authenticated to. Optionally, put the new location under a specified parent location.

Parameters:

  • name (string): Name of the new location.
  • parent_location_id (Optional[string]): Optional parent location to put the location under. Defaults to creating a location in your organization at root level if you do not provide a location ID.

Raises:

  • GRPCError: This error is raised if an invalid name (such as “”) or invalid parent location ID is passed.

Returns:

my_new_location = await cloud.create_location(name="Robotville",
                                              parent_location_id="111ab12345")

For more information, see the Python SDK Docs.

GetLocation

Get a location by its location ID.

Parameters:

  • location_id (Optional[string]): ID of the location to get. Defaults to the location ID provided at AppClient instantiation.

Raises:

  • GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

location = await cloud.get_location(location_id="123ab12345")

For more information, see the Python SDK Docs.

UpdateLocation

Change the name of a parent location and/or assign it a new location.

Parameters:

  • location_id (string): ID of the location to update.
  • name Optional(string): Optional new name to update the location name to. If nothing is passed, the name is not changed.
  • parent_location_id Optional(string): Optional ID of the new location to move the location to. If nothing is passed, the location does not move. If an empty string is passed, the location moves up to the top level.

Raises:

  • GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

# The following line takes the location with ID "abc12abcde" and moves it
# to be a sub-location of the location with ID "xyz34xxxxx"
my_updated_location = await cloud.update_location(
    location_id="abc12abcde",
    name="",
    parent_location_id="xyz34xxxxx",
)

# The following line changes the name of the location without changing its
# parent location
my_updated_location = await cloud.update_location(
    location_id="abc12abcde",
    name="Land Before Robots"
)

# The following line moves the location back up to be a top level location
# without changing its name
my_updated_location = await cloud.update_location(
    location_id="abc12abcde",
    name="",
    parent_location_id=""
)

For more information, see the Python SDK Docs.

DeleteLocation

Delete a location.

Parameters:

  • location_id (string): ID of the location to delete.

Raises:

  • GRPCError: This error is raised if an invalid location ID is passed.

Returns:

  • None
await cloud.delete_location(location_id="abc12abcde")

For more information, see the Python SDK Docs.

ListLocations

Get a list of all locations under the organization you are currently authenticated to.

Parameters:

  • None

Returns:

locations = await cloud.list_locations()

For more information, see the Python SDK Docs.

LocationAuth

Get a location’s LocationAuth (location secret or secrets).

Parameters:

  • location_id (string): ID of the location to retrieve LocationAuth from. Defaults to the location ID provided at AppClient instantiation.

Raises:

  • GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

loc_auth = await cloud.location_auth(location_id="123xy12345")

For more information, see the Python SDK Docs.

CreateLocationSecret

Create a new location secret.

Parameters:

  • location_id (Optional[string]): ID of the location to generate a new secret for. Defaults to the location ID provided at AppClient instantiation.

Raises:

  • GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

new_loc_auth = await cloud.create_location_secret()

For more information, see the Python SDK Docs.

DeleteLocationSecret

Delete a location secret.

Parameters:

  • location_id (string): ID of the location to delete the secret from. Defaults to the location ID provided at AppClient instantiation.
  • secret_id (string): The id of the secret to delete (not the secret string itself).

Raises:

  • GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.
await cloud.delete_location_secret(
    secret_id="abcd123-456-7890ab-cxyz98-989898xyzxyz")

For more information, see the Python SDK Docs.

GetRobot

Get a machine by its ID.

Parameters:

  • robot_id (string): ID of the machine to get.

Raises:

  • GRPCError: This error is raised if an invalid robot ID is passed.

Returns:

robot = await cloud.get_robot(robot_id="1a123456-x1yz-0ab0-a12xyzabc")

For more information, see the Python SDK Docs.

GetRobotParts

Get a list of all the parts under a specific machine.

Parameters:

  • robot_id (string): ID of the machine to get parts from.

Raises:

  • GRPCError: This error is raised if an invalid robot ID is passed.

Returns:

list_of_parts = await cloud.get_robot_parts(
    robot_id="1a123456-x1yz-0ab0-a12xyzabc")

For more information, see the Python SDK Docs.

GetRobotPart

Get a specific machine part.

Parameters:

  • robot_part_id (string): ID of the machine part to get.
  • dest (Optional[string]): Optional filepath to write the machine part’s config in JSON format to.
  • indent (int): Size (in number of spaces) of indent when writing the JSON config to dest. Defaults to 4.

Returns:

my_robot_part = await cloud.get_robot_part(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

GetRobotPartLogs

Get the logs associated with a specific machine part.

Parameters:

  • robot_part_id (string): ID of the machine part to get logs from.
  • filter (Optional[string]): Only include logs with messages that contain the string filter. Defaults to empty string "", meaning no filter.
  • dest (Optional[string]): Optional filepath to write the log entries to.
  • errors_only (bool): (Optional) Specifies whether to limit returned log messages to error logs only. Defaults to True, including only error-level messages by default.
  • num_log_entries (int): Number of log entries to return. Passing 0 returns all logs. Defaults to 100. All logs or the first num_log_entries logs will be returned, whichever comes first.

Raises:

  • GRPCError: This error is raised if an invalid robot part ID is passed.

Returns:

part_logs = await cloud.get_robot_part_logs(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22", num_log_entries=20)

For more information, see the Python SDK Docs.

TailRobotPartLogs

Get an asynchronous iterator that receives live machine part logs.

Parameters:

  • robot_part_id (string): ID of the machine part to retrieve logs from.
  • errors_only (bool): (Optional) Specifies whether to limit returned log messages to error logs only. Defaults to True, including only error-level messages by default.
  • filter (Optional[string]): Only include logs with messages that contain the string filter. Defaults to empty string "", meaning no filter.

Returns:

  • (_LogsStream[List[LogEntry]]): The asynchronous iterator receiving live machine part logs.
logs_stream = await cloud.tail_robot_part_logs(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

GetRobotPartHistory

Get a list containing the history of a machine part.

Parameters:

  • robot_part_id (string): ID of the machine part to retrieve history from.

Raises:

  • GRPCError: This error is raised if an invalid machine part ID is passed.

Returns:

part_history = await cloud.get_robot_part_history(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

UpdateRobotPart

Change the name of and assign an optional new configuration to a machine part.

Parameters:

  • robot_part_id (string): ID of the machine part to update.
  • name (string): New name to be updated on the machine part.
  • robot_config (Mapping[str, Any]): Optional new config represented as a dictionary to be updated on the machine part. The machine part’s config remains unchanged if a new robot_config is not passed.

Raises:

  • GRPCError: This error is raised if an invalid machine part ID, name, or config is passed.

Returns:

my_robot_part = await cloud.update_robot_part(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

NewRobotPart

Create a new machine part.

Parameters:

Raises:

  • GRPCError: This error is raised if an invalid machine ID is passed.

Returns:

new_part_id = await cloud.new_robot_part(
    robot_id="1a123456-x1yz-0ab0-a12xyzabc", part_name="myNewSubPart")

For more information, see the Python SDK Docs.

DeleteRobotPart

Delete the specified machine part.

Parameters:

  • robot_part_id (string): ID of the machine part to delete.

Raises:

  • GRPCError: This error is raised if an invalid machine part ID is passed.
await cloud.delete_robot_part(
    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

MarkPartAsMain

Mark a machine part as the main part of a machine.

Parameters:

  • robot_part_id (string): ID of the machine part to mark as main.

Raises:

  • GRPCError: This error is raised if an invalid machine part ID is passed.
await cloud.mark_part_as_main(
  robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

MarkPartForRestart

Mark a specified machine part for restart.

Parameters:

  • robot_part_id (string): ID of the machine part to mark for restart.

Raises:

  • GRPCError: This error is raised if an invalid machine part ID is passed.
await cloud.mark_part_for_restart(
  robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

CreateRobotPartSecret

Create a machine part secret.

Parameters:

  • robot_part_id (string): ID of the machine part to create a secret for.

Raises:

  • GRPCError: This error is raised if an invalid machine part ID is passed.

Returns:

part_with_new_secret = await cloud.create_robot_part_secret(
  robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")

For more information, see the Python SDK Docs.

DeleteRobotPartSecret

Delete a machine part secret.

Parameters:

  • robot_part_id (string): ID of the machine part to delete the secret from.
  • secret_id (Optional[string]): ID of the secret to delete.

Raises:

  • GRPCError: This error is raised if an invalid machine part ID or secret ID is passed.
await cloud.delete_robot_part_secret(
  robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22",
  secret_id="123xyz12-abcd-4321-12ab-12xy1xyz12xy")

For more information, see the Python SDK Docs.

ListRobots

Get a list of all machines in a specified location.

Parameters:

  • location_id (string): ID of the location to retrieve the machines from.

Raises:

  • GRPCError: This error is raised if an invalid location ID is passed.

Returns:

list_of_machines = await cloud.list_robots(location_id="123ab12345")

For more information, see the Python SDK Docs.

NewRobot

Create a new machine.

Parameters:

  • name (string): Name of the new machine.
  • location_id (Optional[string]): ID of the location to create the new machine in. Defaults to the current authorized location.

Raises:

  • GRPCError: This error is raised if an invalid location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation.

Returns:

new_machine_id = await cloud.new_robot(name="beepboop")

For more information, see the Python SDK Docs.

UpdateRobot

Change the name of an existing machine.

Parameters:

  • robot_id (string): ID of the machine to update.
  • name (string): New name for the machine.
  • location_id (Optional[string]): ID of the location in which the machine exists. Defaults to the location ID provided at AppClient instantiation.

Raises:

  • GRPCError: This error is raised if an invalid machine ID, name, or location ID is passed, or if one isn’t passed and no location ID was provided at AppClient instantiation. Returns:

  • (viam.proto.app.Robot): The newly updated machine.

updated_robot = await cloud.update_robot(
  robot_id="1a123456-x1yz-0ab0-a12xyzabc",
  name="Orange-Robot")

For more information, see the Python SDK Docs.

DeleteRobot

Delete a specified machine.

Parameters:

  • robot_id (string): ID of the machine to delete.

Raises:

  • GRPCError: This error is raised if an invalid machine ID is passed.
await cloud.delete_robot(robot_id="1a123456-x1yz-0ab0-a12xyzabc")

For more information, see the Python SDK Docs.

ListFragments

Get a list of fragments in the organization you are currently authenticated to.

Parameters:

  • show_public (bool): (Optional) Specify whether to only show public fragments. If True, only public fragments will be returned. If False, only private fragments will be returned. Default: True.

Returns:

fragments_list = await cloud.list_fragments(show_public=False)

For more information, see the Python SDK Docs.

GetFragment

Get a fragment by ID.

Parameters:

  • fragment_id (string): ID of the fragment to get.

Raises:

  • GRPCError: This error is raised if an invalid fragment ID is passed.

Returns:

# Get a fragment and print its name and when it was created.
the_fragment = await cloud.get_fragment(
  fragment_id="12a12ab1-1234-5678-abcd-abcd01234567")
print("Name: ", the_fragment.name, "\nCreated on: ", the_fragment.created_on)

For more information, see the Python SDK Docs.

CreateFragment

Create a new private fragment.

Parameters:

  • name (string): Name of the new fragment.
  • config (Optional[Mapping[str, Any]]): Dictionary representation of the new config to assign to the fragment. Can be assigned by updating the fragment.

Raises:

  • GRPCError: This error is raised if an invalid name is passed.

Returns:

new_fragment = await cloud.create_fragment(
  name="cool_smart_machine_to_configure_several_of")

For more information, see the Python SDK Docs.

UpdateFragment

Update a fragment name and its config and/or visibility.

Parameters:

  • fragment_id (string): ID of the fragment to update.
  • name (string): New name to associate with the fragment.
  • config (Optional[Mapping[str, Any]]): Dictionary representation of the new config to assign to the fragment. Not passing this parameter will leave the fragment’s config unchanged.
  • public (bool): Specify whether the fragment is public. Default: False (private).

Raises:

  • GRPCError: This error is raised if an invalid fragment ID, name, or config is passed.

Returns:

updated_fragment = await cloud.update_fragment(
  fragment_id="12a12ab1-1234-5678-abcd-abcd01234567",
  name="better_name")

For more information, see the Python SDK Docs.

DeleteFragment

Delete a fragment.

Parameters:

  • fragment_id (string): ID of the fragment to delete.

Raises:

  • GRPCError: This error is raised if an invalid fragment ID is passed.
await cloud.delete_fragment(
  fragment_id="12a12ab1-1234-5678-abcd-abcd01234567")

For more information, see the Python SDK Docs.

AddRole

Add a role under the organization you are currently authenticated to.

Parameters:

  • identity_id (string): ID of the entity the role belongs to (for example, a user ID).
  • role (string): The role to add (either "owner" or "operator").
  • resource_type (string): The type of the resource to add the role to (either "organization", "location", or "robot"). Must match the type of the resource_id’s resource.
  • resource_id (string): ID of the resource the role applies to (the ID of either an organization, location, or machine.)

Raises:

  • GRPCError: This error is raised if an invalid identity ID, role, resource type, or resource ID is passed.
await cloud.add_role(
  identity_id="abc01234-0123-4567-ab12-a11a00a2aa22",
  role="owner",
  resource_type="location",
  resource_id="111ab12345")

For more information, see the Python SDK Docs.

RemoveRole

Remove a role under the organization you are currently authenticated to.

Parameters:

  • identity_id (string): ID of the entity the role belongs to (for example, a user ID).
  • role (string): The role to remove (either "owner" or "operator").
  • resource_type (string): The type of the resource to remove the role from (either "organization", "location", or "robot"). Must match the type of the resource_id’s resource.
  • resource_id (string): ID of the resource the role applies to (the ID of either an organization, location, or machine.)

Raises:

  • GRPCError: This error is raised if an invalid identity ID, role, resource type, or resource ID is passed.
await cloud.remove_role(
  identity_id="abc01234-0123-4567-ab12-a11a00a2aa22",
  role="owner",
  resource_type="location",
  resource_id="111ab12345")

For more information, see the Python SDK Docs.

ListAuthorizations

List all authorizations (owners and operators) of a specific resource (or resources) within the organization you are currently authenticated to. If no resource IDs are provided, all resource authorizations within the organizations are returned.

Parameters:

  • resource_ids (Optional[List(string)]): IDs of the resources to retrieve authorizations from. Defaults to none.

Raises:

  • GRPCError: This error is raised if an invalid resource ID is passed.

Returns:

list_of_auths = await cloud.list_authorizations(
  resource_ids=["1a123456-x1yz-0ab0-a12xyzabc"])

For more information, see the Python SDK Docs.

CreateModule

Create a module under the organization you are currently authenticated to.

Parameters:

  • name (string): The name of the module. Must be unique within your organization.

Raises:

  • GRPCError: This error is raised if an invalid name (for example, "") is passed.

Returns:

  • (Tuple[string, string]): A tuple containing the ID [0] of the new module and its URL [1].
new_module = await cloud.create_module(name="cool_new_hoverboard_module")
print("Module ID:", new_module[0])

For more information, see the Python SDK Docs.

UpdateModule

Update the documentation URL, description, models, entrypoint, and/or the visibility of a module.

Parameters:

  • module_id (string): ID of the module being updated, containing module name (for example, "my-module") or namespace and module name (for example, "my-org:my-module").
  • url (string): The URL to reference for documentation and code (not the URL of the module itself).
  • description (string): A short description of the module that explains its purpose.
  • models (Optional[List[viam.proto.app.Model]]): List of models that are available in the module.
  • entrypoint (string): The executable to run to start the module program.
  • public (bool): Set the visibility of the module. Defaults to False (private).

Raises:

  • GRPCError: This error is raised if an invalid module ID, URL, list of models, or organization ID is passed.

Returns:

  • (string): The URL of the newly updated module.
url_of_my_module = await cloud.update_module(
  module_id="my-group:cool_new_hoverboard_module",
  url="https://docsformymodule.viam.com",
  description="A base to support hoverboards.",
  entrypoint="exec")

For more information, see the Python SDK Docs.

UploadModuleFile

Upload a module file.

Parameters:

Returns:

file_id = await cloud.upload_module_file(file=b"<file>")

For more information, see the Python SDK Docs.

GetModule

Get a module by its ID.

Parameters:

  • module_id (string): ID of the module being retrieved, containing module name (for example, "my-module") or namespace and module name (for example, "my-org:my-module").

Raises:

  • GRPCError: This error is raised if an invalid module ID is passed.

Returns:

the_module = await cloud.get_module(module_id="my-cool-modular-base")

For more information, see the Python SDK Docs.

ListModules

List the modules under the organization you are currently authenticated to.

Raises:

  • GRPCError: This error is raised if an invalid machine ID is passed.

Returns:

modules_list = await cloud.list_modules()

For more information, see the Python SDK Docs.

CreateOrganizationInvite

Create an organization invite and send it by email.

Parameters:

Returns:

  • None.

Raises:

  • GRPCError: This error is raised if an invalid email is provided, or if the user is already a member of the org.
await cloud.create_organization_invite("youremail@email.com")

For more information, see the Python SDK Docs.

DeleteOrganizationMember

Remove a member from the organization you are currently authenticated to.

Parameters:

  • user_id (str): The ID of the user to remove.

Returns:

  • None.
member_list, invite_list = await cloud.list_organization_members()
first_user_id = member_list[0].user_id

await cloud.delete_organization_member(first_user_id)

For more information, see the Python SDK Docs.

DeleteOrganizationInvite

Delete a pending organization invite to the organization you are currently authenticated to.

Parameters:

  • email (str): The email address the pending invite was sent to.

Returns:

  • None.

Raises:

  • GRPCError: This error is raised if no pending invite is associated with the provided email address.
await cloud.delete_organization_invite("youremail@email.com")

For more information, see the Python SDK Docs.

ResendOrganizationInvite

Resend a pending organization invite email.

Parameters:

  • email (str): The email address associated with the invite.

Returns:

  • None.

Raises:

  • GRPCError: This error is raised if no pending invite is associated with the provided email address.
await cloud.resend_organization_invite("youremail@email.com")

For more information, see the Python SDK Docs.

GetRoverRentalRobots

Return a list of rover rental robots within an organization.

Parameters:

  • None.

Returns:

rental_robots = await cloud.get_rover_rental_robots()

For more information, see the Python SDK Docs.

CheckPermissions

Check if the organization, location, or robot your ViamClient is authenticated to is permitted to perform some action or set of actions on the resource you pass to the method.

Parameters:

Returns:

Raises:

  • GRPCError: This error is raised if the list of permissions to validate is empty.
from viam.proto.app import AuthorizedPermissions

# Check whether the entity you're currently
# authenticated to has permission to control
# and/or read logs from robots
# in the "organization-identifier123" org
permissions = [AuthorizedPermissions(resource_type="organization",
                                     resource_id="organization-identifier123",
                                     permissions=["control_robot",
                                                  "read_robot_logs"])]

filtered_permissions = await cloud.check_permissions(permissions)

For more information, see the Python SDK Docs.

Valid arguments for permissions are as follows:

Click to see permissions strings available

For more information about managing permissions, see Role-Based Access Control.

CreateKey

Create a new API key.

Parameters:

Returns:

Raises:

  • GRPCError: This error is raised if the authorizations list is empty.
from viam.app.app_client import APIKeyAuthorization

auth = APIKeyAuthorization(
  role="owner",
  resource_type="robot",
  resource_id="your-robot-id123"
)

api_key, api_key_id = cloud.create_key([auth], "my_key")

For more information, see the Python SDK Docs.

CreateKeyFromExistingKeyAuthorizations

Create a new API key with an existing key’s authorizations.

Parameters:

  • id (str): The ID of the API key to duplicate authorizations from.

Returns:

api_key, api_key_id = cloud.create_key_from_existing_key_authorizations(
  id="INSERT YOUR API KEY ID")

For more information, see the Python SDK Docs.

ListKeys

List all keys for the organization that you are currently authenticated to.

Parameters:

  • None.

Returns:

keys = cloud.list_keys()

For more information, see the Python SDK Docs.



Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.