Manage Robots in the Account

A Robot is a special super user that allows programmatic access to an entire organizational account. It can create, read, update, and delete any information across all workspaces in the organizational account.

A robot can only be used programmatically. In other words, you cannot log in as a robot. You can only use the APIs.

Robot accounts are immensely powerful. Care must be taken to ensure credentials do not end up in the wrong hands, and that people who are to be trusted with credentials are carefully vetted.

Robots can only be managed by the Owner or Co-Owners of an organizational account.

Administrators cannot manage robots.

Individual robot access can be shared to any member of the account.

Finding the Robot Integration Settings Page

If you are the Owner or a Co-Owner of an organizational account you can:

  1. Go to the Account administration tool in the top bar.
  2. Select the Settings tab
  3. Click Integration settings (robots)

find_robots.png

The integration settings page includes a list of your existing robots, informing you of:

  1. The name of the robot.
  2. Whether the robot can manipulate data in your organization or if it is read-only.
  3. How many account members the robot credentials are currently being shared with.
  4. A dialogue allowing the creation of new robots.

 

robot_list.png

Clicking on a row will lead you to individual settings for that specific robot.

Creating and Editing a New Robot

Once in the robot management section you can:

  1. Read the API terms of use
  2. Check Yes, I understand and want to continue if you approve of the terms.
  3. Click Create.

new_robot.png

A robot will now be instantly created with some default values that you will want to modify.

  1. The name of the robot will default to New robot. Update this to something more descriptive of the robot's purpose. The name can always be changed at a later date.
  2. Use the description field to summarize the purpose of the robot.
  3. Important: Decide whether the robot really needs to be capable of manipulating data in your organizational account. Opt for read-only access if you are unsure. This setting can always be changed at a later date.
  4. Once happy with the settings, click Update.

edit_robot.png

 

Sharing a Robot

NEVER send credentials in an email or through any other communication channel.

Use only the sharing functionality discussed here. This allows you to securely share credentials with the intended people, without the possibility of interception by third-parties.

Robots can only be shared with members and administrators of your organizational account.

Go to the settings of a specific robot.

  1. Find the Shared with section.
  2. In the Select member dropdown, pick a member.
  3. Click Add member to save the sharing setting.

The individual you have shared with gets an email prompting them to sign in to view the robot credentials.

share_robot.png

Unsharing a Robot

You can always remove a user's access to the robot's credentials by clicking the Remove button in the list of members you have shared with.

Unsharing does not invalidate existing credentials. Unsharing only means that from this point onward the user will not be able to find the credentials after having signed in. For example, if the user has written a script using previously shared robot credentials, that script will still be working even after unsharing them to that user.

The only way to invalidate robot credentials is to delete the robot and instead create a new one.

unshare_robot.png  

 

View Robot Credentials

As an Owner or Co-Owner of the organizational account, you can always find the keys and secrets needed to interact with the APIs.

There are two sets of credentials for each Robot, both of which are also visible to any member that the robot has been shared to.

  1. Client ID and Client Secret are needed for both the OAuth1 and OAuth2 Client Credentials flow.
  2. OAuth1 Token and OAuth1 Token Secret are only needed for OAuth1.
  3. The visibility of ach set of credentials can be toggled by clicking the unhide button.
  4. The OAuth1 token can be regenerated. Note that this will invalidate the previous oauth1 token.

OAuth1 is still supported by ProjectPlace. But it is no longer the recommended way to use a robot.

Opt for the OAuth2 Client Credentials flow whenever possible.

Read more about OAuth1 and OAuth2 here.

robot_credentials.png

Deleting a Robot

Deleting a robot immediately invalidates associated credentials. This means that integrations using these credentials will immediately stop working.

Deletion is irreversible.

Don't be overly scared about deleting robot accounts. You can always create a new robot and use those new credentials instead of the old ones. While the credentials are lost forever, whatever integrations you have set up can always be populated with credentials from a new robot.

  1. Indicate you understand that the deletion is not reversible by checking the checkbox.
  2. Click Delete.

delete_robot.png