Terraform Enterprise - Invite users to multiple teams programmatically – HashiCorp Help Center

Introduction

This guide provides an example of how to programmatically invite new users to a Terraform Enterprise organization and assign them to multiple teams using the API.

Prerequisites

A user account with Site admin or Organization owner permissions.
An existing Terraform Enterprise organization with at least two teams.
jq installed to filter JSON responses for readability.

This guide uses the following APIs:

Procedure

This procedure uses an example organization named myorg with two teams, team1 and team2.

1. Generate an Organization API Token

Organization API tokens allow access to organization-level settings and resources without being tied to a specific user. You can use this token to manage teams, team memberships, and workspaces.

Navigate to your Terraform Enterprise organization settings for API tokens. You can find this at https://<your-TFE-FQDN>/app/<your-organization-name>/settings/authentication-tokens.
Click Generate an organization token.
In the pop-up window, click Generate token.
Click the copy button to copy the token to your clipboard. Ensure that you save this token, as you cannot display it again.

2. Set Environment Variables

Export your organization token and Terraform Enterprise FQDN as environment variables to use in subsequent API calls.

Export your organization token.

$ export TOKEN="<PASTE_YOUR_TOKEN_HERE>"

Export your Terraform Enterprise FQDN.

$ export MY_TFE_FQDN="<YOUR_TFE_FQDN_HERE>"

3. Retrieve Organization and Team IDs

Next, use the API to find the names and IDs of your organization and teams.

List your organizations using the Organizations API. An organization token only returns the organization it belongs to.

$ curl \
    --header "Authorization: Bearer $TOKEN" \
    --header "Content-Type: application/vnd.api+json" \
    --request GET "https://$MY_TFE_FQDN/api/v2/organizations" | jq '.data[] | "\(.id)"'

Example output:

"myorg"

Export your organization name as an environment variable.
```
$ export MY_ORG="myorg"
```

List the teams in your organization using the Teams API to retrieve their IDs.

$ curl \
    --header "Authorization: Bearer $TOKEN" \
    --header "Content-Type: application/vnd.api+json" \
    --request GET https://$MY_TFE_FQDN/api/v2/organizations/$MY_ORG/teams | jq '.data[] | "\(.id), \(.attributes.name)"'

Example output:

"team-FAiADfUraMZ2xWUJ, owners"
"team-rTaPDZyg7TeSX7ju, team1"
"team-sugLN6aouN6N3R9q, team2"

Note the team IDs for the teams you want to add the user to. In this example, the IDs are team-rTaPDZyg7TeSX7ju for team1 and team-sugLN6aouN6N3R9q for team2.

4. Invite a User to Multiple Teams

This example invites user1@yourcompany.com to team1 and team2.

Create a JSON file named payload.json with the user's email and the target team IDs.

{
  "data": {
    "attributes": {
      "email": "user1@yourcompany.com"
    },
    "relationships": {
      "teams": {
        "data": [
          {
            "type": "teams",
            "id": "team-rTaPDZyg7TeSX7ju"
          },
          {
            "type": "teams",
            "id": "team-sugLN6aouN6N3R9q"
          }
        ]
      }
    },
    "type": "organization-memberships"
  }
}

Use the Organization Memberships API to send the invitation.

$ curl \
    --header "Authorization: Bearer $TOKEN" \
    --header "Content-Type: application/vnd.api+json" \
    --request POST \
    --data @payload.json \
    https://$MY_TFE_FQDN/api/v2/organizations/$MY_ORG/organization-memberships

5. Verify the Invitation

List the organization members to confirm the user was invited with the correct team assignments.

Use the Organization Memberships API to list all members.

$ curl \
    --header "Authorization: Bearer $TOKEN" \
    --header "Content-Type: application/vnd.api+json" \
    https://$MY_TFE_FQDN/api/v2/organizations/$MY_ORG/organization-memberships | jq -r '.data[] | "\(.attributes.email), \(.attributes.status), \(.relationships.teams.data | map(.id) | join(", "))"'

Review the output. The new user's status should be invited. After the user accepts the invitation, the status will change to active.

Example output:
```
youradmin@yourcompany.com, active, team-FAiADfUraMZ2xWUJ
user1@yourcompany.com, invited, team-rTaPDZyg7TeSX7ju, team-sugLN6aouN6N3R9q
```

Cleanup

To remove an invited user, follow these steps.

Navigate to your organization's user settings page at https://<your-TFE-FQDN>/app/<your-organization-name>/settings/users?filter=invited.
Click the three dots next to the user you want to delete.
Click Remove from the organization.

Additional Information

For more information about the different APIs and their use, refer to the HCP Terraform API Documentation.