Terraform Enterprise - Invite users to multiple teams programmatically

Avatar
Stamatios Chrysinas
  • Updated

Introduction

This guide has an example on how to invite users for first time to a Terraform Enterprise organization and add them in multiple teams programmatically. 

Use Case

As a Terraform Enterprise administrator or Organization owner you want to invite users for first time to your Terraform Organization and assign them multiple teams using HCP Terraform APIs.

Prerequisites 

Before we start

In this example we have a Terraform Enterprise instance with one organization and four teams.
The organization name is:

  • myorg

The four teams are:

  • team1
  • team2

The organization's admin has the email:

  • youradmin@yourcompany.com

The following APIs will be used:

The responses of all API calls in this guide are filtered with jq in order to have user friendly output . You can use the API calls without jq filtering to see the full json response of every API call on your computer.

Procedure

Generate an Organization API token 

Organization API tokens may be generated for a specific organization and allow access to the organization-level settings and resources, without being tied to any specific team or user.
The organization API token is used to manage teams, team membership and workspaces. This token does not have permission to perform plans and applies in workspaces. 

How to generate an Organization API token:

  • In a browser, navigate to your TFE Organization -> Settings -> API Tokens
    or use the following URL and replace the FQDN and the Organization name: 
https://<your-TFE-FQDN>/app/<your-organization-name>/settings/authentication-tokens
  • Click Generate an organization token.

 

  • On the pop up window click Generate token.

  • Click the copy button to copy the Organization Token to your clipboard. 
    You will not be able to display this token again. Make sure you captured it.

 

 

List your organizations and teams programmatically

  • Export your organization token as an environment variable.
    On your command line tool type (replace the value with your token):
export TOKEN="<paste-your-token-here>"
  • Export your Terraform Enterprise FQDN as an environment variable.
    On your command line tool type (replace the value with your FQDN):
export MY_TFE_FQDN="<type-your-TFE-FQDN-here>"
  • Use Organizations API to list your organizations and get your organization name.
    Run the following:
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"

You see only one organization name even if you have more than one organization. This is because of the use of the Organization Token in the API call. If you want to get all the organizations consider using a user API token.

 

  • Export your organization id (name) as an environment variable (replace the value with your organization name):
export MY_ORG="myorg"
  • Use Teams API to list the teams in your organization.
    Run the following:
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 response: 

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

In the example response you see the team id and team name in the same line. You need the team ids on the next step.

 

Invite a user in multiple teams in your organizations programmatically

Let's assume that you want to invite the user with email: user1@yourcompany.com

in two teams, team team1 and team2.
You will need the team ids from the previous step.

  • team1 has id: team-rTaPDZyg7TeSX7ju
  • team2 has id: team-sugLN6aouN6N3R9q

----

Create a json file with name payload.json

  • Paste in the file the content below and replace the team ids with your team ids:
{
  "data": {
    "attributes": {
      "email": "user1@yourcompany.com"
    },
    "relationships": {
      "teams": {
        "data": [
          {
            "type": "teams",
            "id": "<use-team1-id-here>"
          },
          {
            "type": "teams",
            "id": "<use-team2-id-here>"
          }
        ]
      }
     },
     "type": "organization-memberships"
  }
}

 

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

Example unfiltered response:

{
  "data": {
    "id": "ou-59JUxnBUHFtshQer",
    "type": "organization-memberships",
    "attributes": {
      "status": "invited",
      "email": "user1@yourcompany.com",
      "created-at": "2024-12-11T12:28:05.487Z",
      "is-org-two-factor-required?": false
    },
    "relationships": {
      "teams": {
        "data": [
          {
            "id": "team-rTaPDZyg7TeSX7ju",
            "type": "teams"
          },
          {
            "id": "team-sugLN6aouN6N3R9q",
            "type": "teams"
          }
        ]
      },
      "user": {
        "data": {
          "id": "user-wDAs9p3HexKGbQwm",
          "type": "users"
        }
      },
      "organization": {
        "data": {
          "id": "myorg",
          "type": "organizations"
        }
      }
    }
  },
  "included": [
    {
      "id": "user-wDAs9p3HexKGbQwm",
      "type": "users",
      "attributes": {
        "username": null,
        "is-service-account": false,
        "avatar-url": "https://www.gravatar.com/avatar/7796cd6834bec250cc362ab93836172b?s=100&d=mm",
        "two-factor": {
          "enabled": false,
          "verified": false
        },
        "email": "user1@yourcompany.com",
        "permissions": {
          "can-create-organizations": false,
          "can-view-settings": false,
          "can-view-profile": false,
          "can-change-email": false,
          "can-change-username": false,
          "can-change-password": false,
          "can-manage-sessions": false,
          "can-manage-sso-identities": false,
          "can-manage-user-tokens": false,
          "can-update-user": false,
          "can-reenable-2fa-by-unlinking": true,
          "can-manage-hcp-account": false
        }
      },
      "relationships": {
        "authentication-tokens": {
          "links": {
            "related": "/api/v2/users/user-wDAs9p3HexKGbQwm/authentication-tokens"
          }
        },
        "github-app-oauth-tokens": {
          "links": {
            "related": "/api/v2/users/user-wDAs9p3HexKGbQwm/github-app-oauth-tokens"
          }
        }
      },
      "links": {
        "self": "/api/v2/users/user-wDAs9p3HexKGbQwm"
      }
    }
  ]
}

 

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(", "))"'

Example output:

youradmin@yourcompany.com, active, team-FAiADfUraMZ2xWUJ
user1@yourcompany.com, invited, team-rTaPDZyg7TeSX7ju, team-sugLN6aouN6N3R9q

Here you can see that the user status is "invited", when the users accept the invitations the status will change to "active", same as your status in the first line.

Clean up

  • Navigate to your TFE Organization -> Settings -> Users-> Click Invited tab
    or use the following URL and replace the FQDN and the Organization name: 
https://<your-TFE-FQDN>/app/<your-organization-name>/settings/users?filter=invited
  • Click the tree dots next to the user you want to delete.
  • Click Remove from the organization

 

 

Additional information

Visit HCP Terraform API Documentation to learn more about the different APIs and their use:  https://developer.hashicorp.com/terraform/cloud-docs/api-docs

Articles in this section

See more