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>>
- The API token of the invitee:
-
-
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-xxxxxxxxxxxxxx
this 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.