How to add collaborators to a TDR billing profile

Leyla Tarhan
  • Updated

If you're interested in using Terra on Azure, please email terra-enterprise@broadinstitute.org.

Once you’ve set up billing in the Terra Data Repository (TDR), other team members may need to access the same account. Learn how to add collaborators to your TDR billing profile, so that they can create and share datasets using the same billing account.

Overview: Sharing a TDR billing profile

In order to create and share datasets in TDR, you need access to a billing profile, which can be shared among collaborators. Collaborators’ billing profile privileges depend upon their role:

  • User: Users can use the profile to create datasets, ingest data, and create and manage snapshots on TDR. However, they cannot manage the billing profile itself.
  • Owner: Owners have the same privileges as users, and they can also manage the billing profile. This includes adding and removing collaborators, changing the billing account associated with the profile, and deleting the profile. Whoever creates a billing profile automatically becomes an owner, but a profile can have multiple owners.

Step 1: Find the billing profile's UUID

The first step is to identify your billing profile’s Universally Unique Identifier (UUID). You can do this through the TDR web interface or the Swagger API endpoints.

  • If the billing profile is already associated with a dataset, you can find the profile’s UUID on the dataset’s dashboard on the TDR web interface:
    1.1. Log into data.terra.bio, using the same login that you use for Terra.
    1.2. Click on the datasets tab.
    1.3. Select your dataset.
    1.4. Find the default billing profile ID on the dataset summary tab.
    1.5. Hover your mouse over the profile id, and click on the clipboard symbol that appears to the right of the id to copy it.
    Screenshot of the dataset summary tab for an example dataset on the TDR website. An orange rectangle highlights the default billing profile ID field. A mouse icon is hovering over the clipboard icon to the right of the billing profile ID.

  • Alternatively, use Swagger to retrieve your profile’s id regardless of whether it is already associated with a dataset. You can do this by listing the profiles that you have access to, or by looking up a specific dataset.

    Remember to authorize Swagger every time you use itSee How to authenticate/troubleshoot Swagger for TDR for step-by-step instructions.

    • 1.1. Navigate to the enumerateProfiles Swagger endpoint.
      1.2. Authorize Swagger (see instructions above).
      1.3. Click try it out.
      1.4. Check the number in the limit field – if you have access to many billing profiles, you may want to increase this number above the default (10).
      1.5. Click execute.
      1.6. Identify the profile you want to modify among the results returned in the Response Body.
      1.7. Copy the id field for that profile.
      Screenshot of the response body from an enumerateProfiles API call. An orange box highlights the 'id' field.
    • Alternatively, you can look up the profile id for a specific dataset, if one already exists.
      1.1. Copy the Dataset ID from the dataset’s dataset summary tab on the TDR web interface.
      1.2. Navigate to the retrieveDatasetSummary Swagger endpoint.
      1.3. Authorize Swagger (see instructions above).
      1.4. Click try it out.
      1.5. Paste the dataset ID into the id field.
      1.6. Copy the default profile id field from the response body.
      Screenshot of the response body from a retrieveDatasetSummary API call. An orange rectangle highlights the 'defaultProfileID' field.

Step 2: Add a collaborator to the billing profile

Only billing profile owners can add collaborators to a billing profile To check whether you are an owner on the profile, use the retrieveProfilePolicies endpoint to list the profile’s owners and users. If you are not listed among the owners, an owner can upgrade your role by running an addProfilePolicyMember job, following the instructions in this section.

2.1. Navigate to the addProfilePolicyMember Swagger endpoint.

2.2. Authorize Swagger (see instructions above).

2.3. Click try it out.

2.4. Paste the billing profile id from Step 1 into the id field.

2.5. Select the role you would like to assign to the collaborator from the policyName drop-down menu.

2.6. Copy the collaborator’s email into the email field of the request body (in quotes). This should be the same email they use to log into Terra or TDR. Note that you can only add one email per addProfilePolicyMember job.

2.7. Click execute.

Screenshot of the request form for the addProfilePolicyMember endpoint. Orange rectangles highlight the 'id', 'policyName', and 'email' fields.

What to expect

Executing the addProfilePolicyMember job will return the specific access group (owner or user) that you tried to modify. Check that your collaborator has been added to this entry, or run a retrieveProfilePolicies job to see the list of collaborators with all levels of access to the billing profile. Note that it may take about a minute for your change to go through.

Use Terra Groups to add several collaborators If you’re adding several collaborators to a billing profile, the best practice is to create a Terra Group that contains all collaborators with a given access level. Then, you can add the Group’s email to the billing profile with a single addProfilePolicyMember job. You can then manage the Group’s membership through the Terra interface.

Learn more about Terra Groups in Managing access to shared data and tools with groups.

How to remove collaborators from a billing profile

If a collaborator leaves a project or their access privileges change, you may want to remove them from a TDR billing profile. The process depends upon whether you’re managing access to the billing profile using a Terra Group.

  • If you’re maintaining a Terra Group with all collaborators who have the same role on a billing profile, remove a collaborator from the Group to remove them from the billing profile:
    1. Log into app.terra.bio.
    2. Click on the three horizontal lines at the top left of the screen.
    3. Click on your name, then Groups.
    4. Select the group you’re using to manage access to this billing profile and role.
    5. Click on the icon with the three vertical dots inside a circle, to the right of the collaborator you want to remove, and select remove user.

    The collaborator will no longer have access to any TDR billing profile role that this group can access.
  • If you’re not using a Terra Group, use the deleteProfilePolicyMember endpoint to remove collaborators from a billing profile, or to change their privileges:
    1. Navigate to the deleteProfilePolicyMember endpoint.
    2. Authorize Swagger (see instructions above).
    3. Click try it out.
    4. Paste the billing profile id into the id field.
    5. Select the collaborator’s current role (owner or user) from the policyName drop-down menu.
    6. Enter the email address that the collaborator uses for Terra and TDR in the email field (not in quotes).
    7. Click Execute.

What to expect

The deleteProfilePolicyMember job will return the specific access group (owner or user) that you tried to modify. Check that your collaborator has been removed from this entry, or run a retrieveProfilePolicies job to see the list of collaborators with all levels of access to the billing profile. Note that it may take about a minute for your change to go through.

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.