Programmatically Send and Accept an Organization Invite in Terraform Enterprise – HashiCorp Help Center

Introduction

Expected Outcome

The host or administrator generates invites via an automated process and the invitee becomes a member of the organization programmatically via an automated workflow.

Prerequisites

The user already exists in Terraform Enterprise without the membership of the host Terraform Enterprise organization.
An API token of the invitee.
The email address of the invitee that is registered in the Terraform Enterprise application.
The target Team ID for the invitee which has the format of team-xxxxxxxxx.
An API token of the host organization that has permission to generate an invitation.
Organization name
With the user/invitee that is associated with the SAML provider, the invite accept API can sometimes encounter the error 401 with a valid API token, this is a result of the API token expiration. Please review if the user is suitable for this approach. The error 401 can also be found in a common scenario where the API token is no longer valid which is considered legitimate and require a new token.

Use Case

Terraform Enterprise organizations may require such workflows that are able to programmatically manage the memberships of users.

Procedure

Prepare the required information, below are the sample data that will be used throughout the articles:
- - The API token of the invitee: <<INVITEE API TOKEN>>
  - The email address of the invitee: <<INVITEE EMAIL>>
  - The team Id: <<TEAM ID>>
  - The API token of the host organization: <<HOST API TOKEN>>
  - Organization name: <<ORGANIZATION NAME>>

Using the email address and the team Id information to construct the payload according to the user invitation API and save the content into invite-payload.json

{
  "data": {
    "attributes": {
      "email": "<<INVITEE EMAIL>>"
    },
    "relationships": {
      "teams": {
        "data": [
          {
            "type": "teams",
            "id": "<<TEAM ID>>"
          }
        ]
      }
    },
    "type": "organization-memberships"
  }
}

Create the invitation using the user invitation API with the payload from invite-payload.json created in the previous step.

TOKEN=<<HOST API TOKEN>>
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @invite-payload.json \
  https://www.example.com/api/v2/organizations/<<ORGANIZATION NAME>>/organization-memberships | jq -r '.data.id'

The result should contain the ID of the organization membership in the format ou-xxxxxxxxxxxxxxthis is the value for <<MEMBERSHIP ID>> in the subsequent steps.
Create the payload for the accept invite API by substituting the <<MEMBERSHIP ID>> with the membership Id from the previous step and saving the content into the file accept-payload.json for the next step.
```
{
  "data": {
    "id": "<<MEMBERSHIP ID>>",
    "type": "organization-memberships",
    "attributes": {
      "status": "active"
    }
  }
}
    
```

Substitute <<MEMBERSHIP ID>> with membership Id from the previous step and the <<INVITEE API TOKEN>> then proceed to accept the invitation using the membership update API.

TOKEN=<<INVITEE API TOKEN>>
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @accept-payload.json \
  https://www.example.com/api/v2/organization-memberships/<<MEMBERSHIP ID>>

The example response message below is from a successful operation.

{
  "data": {
    "id": "ou-SHARn8cSA1vG3NBP",
    "type": "organization-memberships",
    "attributes": {
      "status": "active",
      "email": "testuser@myorg.com",
      "created-at": "2021-10-27T02:37:12.067Z"
    },
    "relationships": {
      "teams": {
        "data": []
      },
      "user": {
        "data": {
          "id": "user-CDwbMfJ2nruR7AwK",
          "type": "users"
        }
      },
      "organization": {
        "data": {
          "id": "myorg",
          "type": "organizations"
        }
      }
    }
  },
  "included": [
...
...
...
  ]
}

In the case of the API returns with error code 401, this is likely related to SAML user session expiration. The user is required to re-login to Terraform Enterprise which indicates that the approach may not be suitable for this user.
```
{
  "errors": [
    {
      "status": "401",
      "title": "unauthorized"
    }
  ]
}
```
If the API fails with the error You cannot update a membership for different user indicates that the API token mismatches with the user that is associated with the membership Id.
```
    {
  "errors": [
    {
      "status": "403",
      "title": "forbidden",
      "detail": "You cannot update a membership for different user"
    }
  ]
}
```

Additional Information

For further clarification/assistance, please contact support at support@hashicorp.com or submit a ticket via our support portal.