A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
Search Terraform documentation » Admin Users APITerraform Enterprise Only: The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance.
The Users Admin API contains endpoints to help site administrators manage user accounts.
» List all usersGET /api/v2/admin/users
This endpoint lists all user accounts in the Terraform Enterprise installation.
» Query ParametersThese are standard URL query parameters . Remember to percent-encode [
as %5B
and ]
as %5D
if your tooling doesn't automatically encode URLs.
Parameter Description q
Optional. A search query string. Users are searchable by username and email address.filter[admin]
Optional. Can be "true"
or "false"
to show only administrators or non-administrators.filter[suspended]
Optional. Can be "true"
or "false"
to show only suspended users or users who are not suspended.page[number]
Optional. If omitted, the endpoint will return the first page.page[size]
Optional. If omitted, the endpoint will return 20 users per page.
This GET endpoint can optionally return related resources, if requested with the include
query parameter . The following resource types are available:
Resource Name Description organizations
A list of organizations that each user is a member of.
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
"https://app.terraform.io/api/v2/admin/users"
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
"https://app.terraform.io/api/v2/admin/users"
» Sample Response{
"data" : [
{
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : true ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"first" : "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"prev" : null ,
"next" : null ,
"last" : "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"prev-page" : null ,
"next-page" : null ,
"total-pages" : 1 ,
"total-count" : 1
} ,
"status-counts" : {
"total" : 1 ,
"suspended" : 0 ,
"admin" : 1
}
}
}
{
"data" : [
{
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : true ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
] ,
"links" : {
"self" : "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"first" : "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20" ,
"prev" : null ,
"next" : null ,
"last" : "https://app.terraform.io/api/v2/admin/users?page%5Bnumber%5D=1&page%5Bsize%5D=20"
} ,
"meta" : {
"pagination" : {
"current-page" : 1 ,
"prev-page" : null ,
"next-page" : null ,
"total-pages" : 1 ,
"total-count" : 1
} ,
"status-counts" : {
"total" : 1 ,
"suspended" : 0 ,
"admin" : 1
}
}
}
» Delete a user accountDELETE /admin/users/:id
This endpoint deletes a user's account from Terraform Enterprise. To prevent unowned organizations, a user cannot be deleted if they are the sole owner of any organizations. The organizations must be given a new owner or deleted first.
Parameter Description :id
The ID of the user to delete.
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb"
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb"
» Suspend a userPOST /admin/users/:id/actions/suspend
Parameter Description :id
The ID of the user to suspend.
This endpoint suspends a user's account, preventing them from authenticating and accessing resources.
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/suspend"
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/suspend"
» Sample Response{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : false ,
"is-suspended" : true ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : false ,
"is-suspended" : true ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
» Re-activate a suspended userPOST /admin/users/:id/actions/unsuspend
Parameter Description :id
The ID of the user to re-activate.
This endpoint re-activates a suspended user's account, allowing them to resume authenticating and accessing resources.
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/unsuspend"
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/unsuspend"
» Sample Response{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : false ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : false ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
» Grant a user administrative privilegesPOST /admin/users/:id/actions/grant_admin
Parameter Description :id
The ID of the user to make an administrator.
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/grant_admin"
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/grant_admin"
» Sample Response{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : true ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : true ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
» Revoke an user's administrative privilegesPOST /admin/users/:id/actions/revoke_admin
Parameter Description :id
The ID of the administrator to demote.
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/revoke_admin"
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/revoke_admin"
» Sample Response{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : false ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : false ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
» Disable a user's two-factor authenticationPOST /admin/users/:id/actions/disable_two_factor
Parameter Description :id
The ID of the user to disable 2FA for.
This endpoint disables a user's two-factor authentication in the situation where they have lost access to their device and recovery codes. Before disabling a user's two-factor authentication, completing a security verification process is recommended to ensure the request is legitimate.
» Sample Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/disable_two_factor"
curl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
"https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/disable_two_factor"
» Sample Response{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : false ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
{
"data" : {
"id" : "user-ZL4MsEKnd6iTigTb" ,
"type" : "users" ,
"attributes" : {
"username" : "myuser" ,
"email" : "myuser@example.com" ,
"avatar-url" : "https://www.gravatar.com/avatar/3a23b75d5aa41029b88b73f47a0d90db?s=100&d=mm" ,
"is-admin" : false ,
"is-suspended" : false ,
"is-service-account" : false
} ,
"relationships" : {
"organizations" : {
"data" : [
{
"id" : "my-organization" ,
"type" : "organizations"
}
]
}
} ,
"links" : {
"self" : "/api/v2/users/myuser"
}
}
}
» Impersonate another userPOST /admin/users/:id/actions/impersonate
Parameter Description :id
The ID of the user to impersonate. It is not possible to impersonate service accounts or your own account.
Impersonation allows an admin to begin a new session as another user in the system; for more information, see Impersonating a User in the Terraform Enterprise administration section.
Note: Impersonation is intended as a UI feature , and this endpoint exists to support that UI.
» Request BodyThis POST endpoint requires a JSON object with the following properties as a request payload.
Key path Type Default Description reason
string A reason for impersonation, which will be recorded in the Audit Log.
» Sample Payload{
"reason" : "Reason for impersonation"
}
{
"reason" : "Reason for impersonation"
}
» Sample Requestcurl \
--header "Cookie: $COOKIE " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/impersonate
curl \
--header "Cookie: $COOKIE " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/admin/users/user-ZL4MsEKnd6iTigTb/actions/impersonate
» End an impersonation sessionPOST /admin/users/actions/unimpersonate
When an admin has used the above endpoint to begin an impersonation session, they can make a request to this endpoint, using the cookie provided originally, in order to end that session and log out as the impersonated user.
This endpoint does not respond with a body, but the response does include a Set-Cookie
header to persist a new session as the original admin user. As such, this endpoint will have no effect unless the client is able to persist and use cookies.
» Sample Requestcurl \
--header "Cookie: $COOKIE " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
https://app.terraform.io/api/v2/admin/users/actions/unimpersonate
curl \
--header "Cookie: $COOKIE " \
--header "Content-Type: application/vnd.api+json" \
--request POST \
https://app.terraform.io/api/v2/admin/users/actions/unimpersonate