HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register

HashiCorp IAM Service

API for managing Identity and Access Management.

Download Spec

Operations

ListServicePrincipals2

/iam/{parent_resource_name_1}/service-principals

https://api.cloud.hashicorp.com/2019-12-10/iam/{parent_resource_name_1}/service-principals

Request

Path Parameters

parent_resource_name_1string

parent_resource_name is the resource name of the project or organization at which the service principal should be listed (e.g. "project/<project_id>" or "organization/<organization_id>")

Query Parameters

pagination.page_sizeinteger

The max number of results per page that should be returned. If the number of available results is larger than page_size, a next_page_token is returned which can be used to get the next page of results in subsequent requests. A value of zero will cause page_size to be defaulted.

pagination.next_page_tokenstring

Specifies a page token to use to retrieve the next page. Set this to the next_page_token returned by previous list requests to get the next page of results. If set, previous_page_token must not be set.

pagination.previous_page_tokenstring

Specifies a page token to use to retrieve the previous page. Set this to the previous_page_token returned by previous list requests to get the previous page of results. If set, next_page_token must not be set.

Response

200 - OK

service_principalsobject[]

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateServicePrincipal2

/iam/{parent_resource_name_1}/service-principals

https://api.cloud.hashicorp.com/2019-12-10/iam/{parent_resource_name_1}/service-principals

Request

Path Parameters

parent_resource_name_1string

parent_resource_name is the resource name of the project or organization at which the service principal should be created (e.g. "project/<project_id>" or "organization/<organization_id>")

Body Parameters

namestring

name is the customer-chosen name for this service principal.

Response

200 - OK

service_principalobject

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListServicePrincipals

/iam/{parent_resource_name}/service-principals

https://api.cloud.hashicorp.com/2019-12-10/iam/{parent_resource_name}/service-principals

Request

Path Parameters

parent_resource_namestring

parent_resource_name is the resource name of the project or organization at which the service principal should be listed (e.g. "project/<project_id>" or "organization/<organization_id>")

Query Parameters

pagination.page_sizeinteger

pagination.next_page_tokenstring

pagination.previous_page_tokenstring

Response

200 - OK

service_principalsobject[]

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateServicePrincipal

/iam/{parent_resource_name}/service-principals

https://api.cloud.hashicorp.com/2019-12-10/iam/{parent_resource_name}/service-principals

Request

Path Parameters

parent_resource_namestring

parent_resource_name is the resource name of the project or organization at which the service principal should be created (e.g. "project/<project_id>" or "organization/<organization_id>")

Body Parameters

namestring

name is the customer-chosen name for this service principal.

Response

200 - OK

service_principalobject

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateServicePrincipalKey2

/{parent_resource_name_1}/keys

https://api.cloud.hashicorp.com/2019-12-10/{parent_resource_name_1}/keys

Request

Path Parameters

parent_resource_name_1string

parent_resource_name is the resource name of the service principal to generate a key for.

Body Parameters

application/jsonobject

Response

200 - OK

keyobject

Key is a service principal key used to authenticate a service principal.

resource_namestring
resource_name is the resource name for this service principal key.
client_idstring
client_id is the non-secret part of the credential set.
created_atstring
created_at is when the Key resource was created.
statestring
State is the state of the key.

UNSET: UNSET is the default value. Should never be used at runtime for valid messages.

CREATING: CREATING is a key that's just been inserted in the DB, and its authN credentials are still being prepared. Will transition to ACTIVE on success.

ACTIVE: ACTIVE is a key that's been properly created and is ready to use.

DELETING: DELETING is a key that it's being deleted. It will be fully deleted once its authN credentials will have been deleted from Auth0.

client_secretstring

client_secret is the secret part of the credential set modelled by the service principal key. Its counterpart is the "client ID", which is part of the key message. This is the only time that this client secret transits through our systems, as after the creation of the service principal key it's forgotten. Consumers of this service endpoint are expected to store the client secret in order to use it later.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateServicePrincipalKey

/{parent_resource_name}/keys

https://api.cloud.hashicorp.com/2019-12-10/{parent_resource_name}/keys

Request

Path Parameters

parent_resource_namestring

parent_resource_name is the resource name of the service principal to generate a key for.

Body Parameters

application/jsonobject

Response

200 - OK

keyobject

Key is a service principal key used to authenticate a service principal.

resource_namestring
resource_name is the resource name for this service principal key.
client_idstring
client_id is the non-secret part of the credential set.
created_atstring
created_at is when the Key resource was created.
statestring
State is the state of the key.

UNSET: UNSET is the default value. Should never be used at runtime for valid messages.

CREATING: CREATING is a key that's just been inserted in the DB, and its authN credentials are still being prepared. Will transition to ACTIVE on success.

ACTIVE: ACTIVE is a key that's been properly created and is ready to use.

DELETING: DELETING is a key that it's being deleted. It will be fully deleted once its authN credentials will have been deleted from Auth0.

client_secretstring

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListWorkloadIdentityProvider

/{parent_resource_name}/workload-identity-providers

https://api.cloud.hashicorp.com/2019-12-10/{parent_resource_name}/workload-identity-providers

Request

Path Parameters

parent_resource_namestring

parent_resource_name is the resource name of the service principal to list workload identity providers from.

Query Parameters

pagination.page_sizeinteger

pagination.next_page_tokenstring

pagination.previous_page_tokenstring

Response

200 - OK

providersobject[]

WorkloadIdentityProvider is an identity provider that federates identity to a service principal.

resource_idstring
resource_id is the resource identifier for this workload identity provider.
resource_namestring
resource_name is the resource name for this workload identity provider.
descriptionstring
description is an optional description for the workload identity provider.
conditional_accessstring
conditional_access is a go-bexpr string that is evaluated when exchanging tokens. It restricts which upstream identities are allowed to access the service principal.
aws_configobject
AWSWorkloadIdentityProviderConfig configures an AWS Workload Identity Provider.
- account_idstring
  account_id is the AWS account ID allowed to exchange identities.
oidc_configobject
OIDCWorkloadIdentityProviderConfig configures an OIDC Workload Identity Provider.
- issuer_uristring
- allowed_audiencesstring[]
system_managedboolean
system_managed indicates that the provider is not editable or deletable by the user.
created_atstring
created_at is when the workload identity provider was created.
updated_atstring
updated_at is when the workload identity provider was last updated.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateWorkloadIdentityProvider

/{parent_resource_name}/workload-identity-providers

https://api.cloud.hashicorp.com/2019-12-10/{parent_resource_name}/workload-identity-providers

Request

Path Parameters

parent_resource_namestring

parent_resource_name is the name of the service principal the workload identity provider will be created under.

Body Parameters

namestring

name is the name of the workload identity provider to be created.

providerobject

WorkloadIdentityProvider is an identity provider that federates identity to a service principal.

resource_idstring
resource_id is the resource identifier for this workload identity provider.
resource_namestring
resource_name is the resource name for this workload identity provider.
descriptionstring
description is an optional description for the workload identity provider.
conditional_accessstring
conditional_access is a go-bexpr string that is evaluated when exchanging tokens. It restricts which upstream identities are allowed to access the service principal.
aws_configobject
AWSWorkloadIdentityProviderConfig configures an AWS Workload Identity Provider.
- account_idstring
  account_id is the AWS account ID allowed to exchange identities.
oidc_configobject
OIDCWorkloadIdentityProviderConfig configures an OIDC Workload Identity Provider.
- issuer_uristring
- allowed_audiencesstring[]
system_managedboolean
system_managed indicates that the provider is not editable or deletable by the user.
created_atstring
created_at is when the workload identity provider was created.
updated_atstring
updated_at is when the workload identity provider was last updated.

Response

200 - OK

providerobject

WorkloadIdentityProvider is an identity provider that federates identity to a service principal.

resource_idstring
resource_id is the resource identifier for this workload identity provider.
resource_namestring
resource_name is the resource name for this workload identity provider.
descriptionstring
description is an optional description for the workload identity provider.
conditional_accessstring
conditional_access is a go-bexpr string that is evaluated when exchanging tokens. It restricts which upstream identities are allowed to access the service principal.
aws_configobject
AWSWorkloadIdentityProviderConfig configures an AWS Workload Identity Provider.
- account_idstring
  account_id is the AWS account ID allowed to exchange identities.
oidc_configobject
OIDCWorkloadIdentityProviderConfig configures an OIDC Workload Identity Provider.
- issuer_uristring
- allowed_audiencesstring[]
system_managedboolean
system_managed indicates that the provider is not editable or deletable by the user.
created_atstring
created_at is when the workload identity provider was created.
updated_atstring
updated_at is when the workload identity provider was last updated.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

UpdateWorkloadIdentityProvider

/{provider.resource_name}

https://api.cloud.hashicorp.com/2019-12-10/{provider.resource_name}

Request

Path Parameters

provider.resource_namestring

resource_name is the resource name for this workload identity provider.

Query Parameters

update_maskstring

update_mask describing which resource attribute(s) to update.

Body Parameters

resource_idstring

resource_id is the resource identifier for this workload identity provider.

descriptionstring

description is an optional description for the workload identity provider.

conditional_accessstring

conditional_access is a go-bexpr string that is evaluated when exchanging tokens. It restricts which upstream identities are allowed to access the service principal.

aws_configobject

AWSWorkloadIdentityProviderConfig configures an AWS Workload Identity Provider.

account_idstring
account_id is the AWS account ID allowed to exchange identities.

oidc_configobject

OIDCWorkloadIdentityProviderConfig configures an OIDC Workload Identity Provider.

issuer_uristring
allowed_audiencesstring[]

system_managedboolean

system_managed indicates that the provider is not editable or deletable by the user.

created_atstring

created_at is when the workload identity provider was created.

updated_atstring

updated_at is when the workload identity provider was last updated.

Response

200 - OK

providerobject

WorkloadIdentityProvider is an identity provider that federates identity to a service principal.

resource_idstring
resource_id is the resource identifier for this workload identity provider.
resource_namestring
resource_name is the resource name for this workload identity provider.
descriptionstring
description is an optional description for the workload identity provider.
conditional_accessstring
conditional_access is a go-bexpr string that is evaluated when exchanging tokens. It restricts which upstream identities are allowed to access the service principal.
aws_configobject
AWSWorkloadIdentityProviderConfig configures an AWS Workload Identity Provider.
- account_idstring
  account_id is the AWS account ID allowed to exchange identities.
oidc_configobject
OIDCWorkloadIdentityProviderConfig configures an OIDC Workload Identity Provider.
- issuer_uristring
- allowed_audiencesstring[]
system_managedboolean
system_managed indicates that the provider is not editable or deletable by the user.
created_atstring
created_at is when the workload identity provider was created.
updated_atstring
updated_at is when the workload identity provider was last updated.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetServicePrincipal2

/{resource_name_1}

https://api.cloud.hashicorp.com/2019-12-10/{resource_name_1}

Request

Path Parameters

resource_name_1string

resource_name is the resource name of the service principal to retrieve.

Response

200 - OK

service_principalobject

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

keysobject[]

Key is a service principal key used to authenticate a service principal.

resource_namestring
resource_name is the resource name for this service principal key.
client_idstring
client_id is the non-secret part of the credential set.
created_atstring
created_at is when the Key resource was created.
statestring
State is the state of the key.

UNSET: UNSET is the default value. Should never be used at runtime for valid messages.

CREATING: CREATING is a key that's just been inserted in the DB, and its authN credentials are still being prepared. Will transition to ACTIVE on success.

ACTIVE: ACTIVE is a key that's been properly created and is ready to use.

DELETING: DELETING is a key that it's being deleted. It will be fully deleted once its authN credentials will have been deleted from Auth0.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteServicePrincipal2

/{resource_name_1}

https://api.cloud.hashicorp.com/2019-12-10/{resource_name_1}

Request

Path Parameters

resource_name_1string

resource_name is the resource name of the service principal to delete.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetWorkloadIdentityProvider

/{resource_name_2}

https://api.cloud.hashicorp.com/2019-12-10/{resource_name_2}

Request

Path Parameters

resource_name_2string

resource_name is the resource name of the workload identity provider to retrieve.

Response

200 - OK

providerobject

WorkloadIdentityProvider is an identity provider that federates identity to a service principal.

resource_idstring
resource_id is the resource identifier for this workload identity provider.
resource_namestring
resource_name is the resource name for this workload identity provider.
descriptionstring
description is an optional description for the workload identity provider.
conditional_accessstring
conditional_access is a go-bexpr string that is evaluated when exchanging tokens. It restricts which upstream identities are allowed to access the service principal.
aws_configobject
AWSWorkloadIdentityProviderConfig configures an AWS Workload Identity Provider.
- account_idstring
  account_id is the AWS account ID allowed to exchange identities.
oidc_configobject
OIDCWorkloadIdentityProviderConfig configures an OIDC Workload Identity Provider.
- issuer_uristring
- allowed_audiencesstring[]
system_managedboolean
system_managed indicates that the provider is not editable or deletable by the user.
created_atstring
created_at is when the workload identity provider was created.
updated_atstring
updated_at is when the workload identity provider was last updated.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteServicePrincipalKey

/{resource_name_2}

https://api.cloud.hashicorp.com/2019-12-10/{resource_name_2}

Request

Path Parameters

resource_name_2string

resource_name is the resource name of the service principal key to delete.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteServicePrincipalKey2

/{resource_name_3}

https://api.cloud.hashicorp.com/2019-12-10/{resource_name_3}

Request

Path Parameters

resource_name_3string

resource_name is the resource name of the service principal key to delete.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteWorkloadIdentityProvider

/{resource_name_4}

https://api.cloud.hashicorp.com/2019-12-10/{resource_name_4}

Request

Path Parameters

resource_name_4string

resource_name is the resource name of the workload identity provider to delete.

Response

200 - OK

resource_namestring

resource_name is the resource name of the workload identity provider that was deleted.

resource_idstring

resource_id is the resource id of the workload identity provider that was deleted.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetServicePrincipal

/{resource_name}

https://api.cloud.hashicorp.com/2019-12-10/{resource_name}

Request

Path Parameters

resource_namestring

resource_name is the resource name of the service principal to retrieve.

Response

200 - OK

service_principalobject

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

keysobject[]

Key is a service principal key used to authenticate a service principal.

resource_namestring
resource_name is the resource name for this service principal key.
client_idstring
client_id is the non-secret part of the credential set.
created_atstring
created_at is when the Key resource was created.
statestring
State is the state of the key.

UNSET: UNSET is the default value. Should never be used at runtime for valid messages.

CREATING: CREATING is a key that's just been inserted in the DB, and its authN credentials are still being prepared. Will transition to ACTIVE on success.

ACTIVE: ACTIVE is a key that's been properly created and is ready to use.

DELETING: DELETING is a key that it's being deleted. It will be fully deleted once its authN credentials will have been deleted from Auth0.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteServicePrincipal

/{resource_name}

https://api.cloud.hashicorp.com/2019-12-10/{resource_name}

Request

Path Parameters

resource_namestring

resource_name is the resource name of the service principal to delete.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ExchangeWorkloadIdentityToken

/{resource_name}/exchange-token

https://api.cloud.hashicorp.com/2019-12-10/{resource_name}/exchange-token

Request

Path Parameters

resource_namestring

resource_name is the resource_name of the workload identity provider to exchange against.

Body Parameters

jwt_tokenstring

jwt_token is a JWT token.

aws_get_caller_id_tokenobject

urlstring
methodstring
bodystring
body is the HTTP request body.
headersobject
x-amz-date: the date of the request host: the host of the request, e.g. sts.amazonaws.com x-hcp-workload-identity-provider: the resource_name of the workload identity provider the token exchange will be conducted against. Authorization: The AWS Signature for the request. X-Amz-Security-Token: The temporary security credentials' session used to sign the request. Described here: https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html#temporary-security-credentials

Response

200 - OK

access_tokenstring

access_token is an access_token with the subject matching that of the requested service principal.

expires_ininteger

expires_in is the number of seconds the returned access token expires in.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

AcceptOrganizationInvitation

/iam/accept-invitation

https://api.cloud.hashicorp.com/iam/2019-12-10/accept-invitation

Request

Body Parameters

invitation_tokenstring

invitation_token is the token to be consumed on successful invitation acceptance.

Response

200 - OK

invitationobject

idstring
organization_idstring
OrganizationId is a reference to the organization that this invitation is for.
inviter_user_principal_idstring
InviterUserPrincipalId the UUID of the user principal who is inviting another person into the organization.
invitee_emailstring
InviteeEmail is the email address that is used as target of the invitation.
created_atstring
CreatedAt is when the record was inserted, that is when the invitation was created and sent.
accepted_atstring
AcceptedAt is when the invitation was accepted, resulting in the invitee being added to the organization. This value can be null, which marks an invitation record as being still pending.
rolestring
role is the globally unique identifier that corresponds to the "id" column in cloud-resource-manager roles table. For now, this field can only have the values "roles/admin", "roles/viewer", "roles/contributor".
statestring
State is one of the states that an organization invitation can be in. The public and private values for State do not map onto each other in a 1-to-1 way.

PENDING: PENDING is the state of an organization invitation that has been created successfully but has not been accepted yet.

ACCEPTED: ACCEPTED is the state of an organization invitation that has been accepted.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetCallerIdentity

/iam/caller-identity

https://api.cloud.hashicorp.com/iam/2019-12-10/caller-identity

Request

No request data.

Response

200 - OK

principalobject

Principal is the common wrapper for our different types of principals.

idstring
id is the identifier for the principal.
typestring
PrincipalType represents the possible types of principals.

PRINCIPAL_TYPE_UNSPECIFIED: PRINCIPAL_TYPE_UNSPECIFIED is the default value.

PRINCIPAL_TYPE_USER: PRINCIPAL_TYPE_USER is the user principal type.

PRINCIPAL_TYPE_SERVICE: PRINCIPAL_TYPE_SERVICE is the service principal type.

PRINCIPAL_TYPE_GROUP: PRINCIPAL_TYPE_GROUP is the group principal type.

PRINCIPAL_TYPE_INTERNAL_OPERATOR: PRINCIPAL_TYPE_INTERNAL_OPERATOR is the internal operator principal type.
userobject
UserPrincipal represents a human user of our platform.
- idstring
  id is the UUID public identifier for a user principal. It is safe to share this value with external users, and it should be how user principals are commonly identified also within our platform.
- emailstring
  email is the unique email address of this user.
- full_namestring
  full_name is the name of the user, as provided by Auth0.
- identity_typestring
  IdentityType contains the identity types for users.
  
  UNSET: UNSET is the default value, should not be used.
  
  SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.
  
  EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.
  
  SAMLP: SAMLP is the auth0 SAML provider.
  
  HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
- identity_typesstring[]
  IdentityType contains the identity types for users.
  
  UNSET: UNSET is the default value, should not be used.
  
  SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.
  
  EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.
  
  SAMLP: SAMLP is the auth0 SAML provider.
  
  HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
- subjectstring
  subject is the user ID from the authenticating IDP (e.g. Hydra).
- scim_synchronizedboolean
  scim_synchronized denotes the user principal was synchronized from a customer's IdP using SCIM.
- tfc_synchronized_atstring
  tfc_synchronized_at denotes the timestamp of when the user was synced to TFC when applicable.
serviceobject
ServicePrincipal is the HCP identity for a machine user.
- idstring
  id is the UUID identifier for this service principal.
- namestring
  name is the name for this service principal.
- resource_namestring
  resource_name is the resource name for this service principal.
- organization_idstring
  organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
- created_atstring
  created_at is when the service principal was created.
- project_idstring
  project_id is the UUID identifier of the HCP project that this project service principal belongs to.
groupobject
- resource_idstring
  resource_id is the principal ID of the group.
- resource_namestring
  resource_name is the name of the group.
- display_namestring
  display_name is the user-specified display name of the group.
- descriptionstring
  description is a description of the group.
- created_atstring
  created_at is when the group was created.
- updated_atstring
  updated_at is when the group was last updated.
- member_countinteger
- scim_synchronizedboolean
  scim_synchronized denotes the group was synchronized from an upstream IdP using SCIM.
group_idsstring[]

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListGroups

/iam/iam/{parent_resource_name}/groups

https://api.cloud.hashicorp.com/iam/2019-12-10/iam/{parent_resource_name}/groups

Request

Path Parameters

parent_resource_namestring

parent_resource is the parent resource of the group. organization/<org_id>

Query Parameters

filter.member_principal_idstring

member_principal_id is an optional query param to filter groups that a principal belongs to.

filter.group_resource_idsstring[]

group_resource_ids is a way to filter groups by a list of group ids when we need to resolve group attributes (e.g. name) from a list of ids we get from a project policy.

pagination.page_sizeinteger

pagination.next_page_tokenstring

pagination.previous_page_tokenstring

Response

200 - OK

groupsobject[]

resource_idstring
resource_id is the principal ID of the group.
resource_namestring
resource_name is the name of the group.
display_namestring
display_name is the user-specified display name of the group.
descriptionstring
description is a description of the group.
created_atstring
created_at is when the group was created.
updated_atstring
updated_at is when the group was last updated.
member_countinteger
scim_synchronizedboolean
scim_synchronized denotes the group was synchronized from an upstream IdP using SCIM.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateGroup

/iam/iam/{parent_resource_name}/groups

https://api.cloud.hashicorp.com/iam/2019-12-10/iam/{parent_resource_name}/groups

Request

Path Parameters

parent_resource_namestring

parent_resource is the parent resource of the group. organization/<org_id>

Body Parameters

namestring

name is the name part of the group resource_name.

descriptionstring

description is a description of the group.

member_principal_idsstring[]

Response

200 - OK

groupobject

resource_idstring
resource_id is the principal ID of the group.
resource_namestring
resource_name is the name of the group.
display_namestring
display_name is the user-specified display name of the group.
descriptionstring
description is a description of the group.
created_atstring
created_at is when the group was created.
updated_atstring
updated_at is when the group was last updated.
member_countinteger
scim_synchronizedboolean
scim_synchronized denotes the group was synchronized from an upstream IdP using SCIM.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CountOrganizationGroups

/iam/iam/{parent_resource_name}/groups/count

https://api.cloud.hashicorp.com/iam/2019-12-10/iam/{parent_resource_name}/groups/count

Request

Path Parameters

parent_resource_namestring

parent_resource is the parent resource of the group. organization/<org_id>

Response

200 - OK

group_countinteger

group_count is the number of groups in the organization.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CountGroupsForPrincipals

/iam/iam/{parent_resource_name}/groups/count-for-principals

https://api.cloud.hashicorp.com/iam/2019-12-10/iam/{parent_resource_name}/groups/count-for-principals

Request

Path Parameters

parent_resource_namestring

parent_resource is the parent resource of the groups that should be counted per principal organization/<org_id>

Query Parameters

principal_idsstring[]

principal_ids is a list of the ids for which to count groups.

Response

200 - OK

principals_countsobject[]

idstring
id is the id of the principal.
countinteger
count is the number of groups this principal is a member of.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CountMembersForGroups

/iam/iam/{parent_resource_name}/groups/count-members-for-groups

https://api.cloud.hashicorp.com/iam/2019-12-10/iam/{parent_resource_name}/groups/count-members-for-groups

Request

Path Parameters

parent_resource_namestring

parent_resource is the parent resource of the groups that the groups should belong. organization/<org_id>

Query Parameters

group_resource_namesstring[]

group_resource_names is a list of the group resource_names for which to count members.

Response

200 - OK

groups_countsobject[]

resource_namestring
resource_name refers to the group.
countinteger
count is the count of members in the group.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetOrganizationNameByInvitationToken

/iam/invitations/{invitation_token}/organization

https://api.cloud.hashicorp.com/iam/2019-12-10/invitations/{invitation_token}/organization

Request

Path Parameters

invitation_tokenstring

Response

200 - OK

organization_namestring

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetCurrentUserPrincipal

/iam/me

https://api.cloud.hashicorp.com/iam/2019-12-10/me

Request

Query Parameters

web_portal_preferencesboolean

web_portal_preferences is a flag indicating whether user's portal preferences need to be included or not. Typically the HCP Web Portal JS application will set this option to true, as its the main consumer of this data. Other clients (e.g. a CLI, a TF provider) will not need to enable it.

Response

200 - OK

user_principalobject

UserPrincipal represents a human user of our platform.

idstring
id is the UUID public identifier for a user principal. It is safe to share this value with external users, and it should be how user principals are commonly identified also within our platform.
emailstring
email is the unique email address of this user.
full_namestring
full_name is the name of the user, as provided by Auth0.
identity_typestring
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
identity_typesstring[]
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
subjectstring
subject is the user ID from the authenticating IDP (e.g. Hydra).
scim_synchronizedboolean
scim_synchronized denotes the user principal was synchronized from a customer's IdP using SCIM.
tfc_synchronized_atstring
tfc_synchronized_at denotes the timestamp of when the user was synced to TFC when applicable.

web_portal_preferencesobject

WebConsolePreferences represents the user preferences for the web portal (fka web console).

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ConfirmMFAEnrollment

/iam/me/confirm-mfa-enrollment

https://api.cloud.hashicorp.com/iam/2019-12-10/me/confirm-mfa-enrollment

Request

Body Parameters

confirmation_otpstring

mfa_tokenstring

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DisableMFA

/iam/me/disable-mfa

https://api.cloud.hashicorp.com/iam/2019-12-10/me/disable-mfa

Request

Body Parameters

mfa_tokenstring

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

EnableMFA

/iam/me/enable-mfa

https://api.cloud.hashicorp.com/iam/2019-12-10/me/enable-mfa

Request

Body Parameters

mfa_tokenstring

Response

200 - OK

qrcode_uristring

secretstring

recovery_codesstring[]

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetMFAStatus

/iam/me/mfa-status

https://api.cloud.hashicorp.com/iam/2019-12-10/me/mfa-status

Request

No request data.

Response

200 - OK

statusstring

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ResetPassword

/iam/me/reset-password

https://api.cloud.hashicorp.com/iam/2019-12-10/me/reset-password

Request

No request data.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

SendVerificationEmail

/iam/me/send-verification-email

https://api.cloud.hashicorp.com/iam/2019-12-10/me/send-verification-email

Request

No request data.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

UpdateWebConsolePreferences

/iam/me/web-portal-preferences

https://api.cloud.hashicorp.com/iam/2019-12-10/me/web-portal-preferences

Request

Body Parameters

web_portal_preferencesobject

WebConsolePreferences represents the user preferences for the web portal (fka web console).

Response

200 - OK

web_portal_preferencesobject

WebConsolePreferences represents the user preferences for the web portal (fka web console).

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetOrganizationAuthMetadata

/iam/organizations/{organization_id}/auth-metadata

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/auth-metadata

Request

Path Parameters

organization_idstring

organization_id is the UUID identifier of the organization for which authentication metadata will be retrieved.

Response

200 - OK

sso_enabledboolean

sso_status indicates whether the organization has configured Single Sign-On via an external IdP.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetAuthConnections

/iam/organizations/{organization_id}/auth_connections

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/auth_connections

Request

Path Parameters

organization_idstring

Response

200 - OK

auth_connectionsobject[]

AuthConnection represents an authentication connection that may be used in multiple message types.

idstring
issuerstring
client_idstring
email_domainstring
created_atstring
updated_atstring
default_rolestring
default_role is the RBAC role that users signing in to the SSO org will get as the default.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteAuthConnectionFromOrganization

/iam/organizations/{organization_id}/auth_connections

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/auth_connections

Request

Path Parameters

organization_idstring

organization_id of the organization that owns the AuthConnection.

Response

200 - OK

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateAuthConnection

/iam/organizations/{organization_id}/auth_connections

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/auth_connections

Request

Path Parameters

organization_idstring

organization_id is the organization that will own the authentication connection.

Body Parameters

issuerstring

issuer is the URL of the identity provider.

client_idstring

client_id is the ID of the client for the connection.

client_secretstring

client_secret is the secret for the client above.

email_domainstring

email_domain associated with the of the connection.

default_rolestring

default_role is the RBAC role that users signing in to the SSO org will get as the default.

Response

200 - OK

auth_connectionobject

AuthConnection represents an authentication connection that may be used in multiple message types.

idstring
issuerstring
client_idstring
email_domainstring
created_atstring
updated_atstring
default_rolestring
default_role is the RBAC role that users signing in to the SSO org will get as the default.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

EditAuthConnection

/iam/organizations/{organization_id}/auth_connections

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/auth_connections

Request

Path Parameters

organization_idstring

id of the organization that owns the connection

Body Parameters

issuerstring

issuer is the URL of the identity provider.

client_idstring

client_id is the ID of the client for the connection.

client_secretstring

client_secret is the secret for the client above.

email_domainstring

email_domain associated with the connection.

update_maskstring

default_rolestring

default_role is the RBAC role that users signing in to the SSO org will get as the default.

Response

200 - OK

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListOrganizationInvitations

/iam/organizations/{organization_id}/invitations

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/invitations

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization for which invites are being requested.

Query Parameters

pagination.page_sizeinteger

pagination.next_page_tokenstring

pagination.previous_page_tokenstring

statesstring[]

States limits the organization invitations to be returned by one or more states.

PENDING: PENDING is the state of an organization invitation that has been created successfully but has not been accepted yet.
ACCEPTED: ACCEPTED is the state of an organization invitation that has been accepted.

Response

200 - OK

invitationsobject[]

idstring
organization_idstring
OrganizationId is a reference to the organization that this invitation is for.
inviter_user_principal_idstring
InviterUserPrincipalId the UUID of the user principal who is inviting another person into the organization.
invitee_emailstring
InviteeEmail is the email address that is used as target of the invitation.
created_atstring
CreatedAt is when the record was inserted, that is when the invitation was created and sent.
accepted_atstring
AcceptedAt is when the invitation was accepted, resulting in the invitee being added to the organization. This value can be null, which marks an invitation record as being still pending.
rolestring
role is the globally unique identifier that corresponds to the "id" column in cloud-resource-manager roles table. For now, this field can only have the values "roles/admin", "roles/viewer", "roles/contributor".
statestring
State is one of the states that an organization invitation can be in. The public and private values for State do not map onto each other in a 1-to-1 way.

PENDING: PENDING is the state of an organization invitation that has been created successfully but has not been accepted yet.

ACCEPTED: ACCEPTED is the state of an organization invitation that has been accepted.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateOrganizationInvitations

/iam/organizations/{organization_id}/invitations

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/invitations

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization to which the invitee is being invited.

Body Parameters

invitationsobject[]

NewOrganizationInvitation contains the data for the creation of a new organization invitation. It's used as part of the request to create a number of org invitations.

invitee_emailstring
invitee_email is the email address of the person who is being invited to join an organization.
rolestring
role is the globally unique identifier that corresponds to the "id" column in cloud-resource-manager roles table. For now, this field can only have the values "roles/admin", "roles/viewer", "roles/contributor".

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteOrganizationInvitation

/iam/organizations/{organization_id}/invitations/{invitation_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/invitations/{invitation_id}

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization for which the invitation is being deleted.

invitation_idstring

invitation_id is the id of the invitation to be deleted.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

BatchGetPrincipals

/iam/organizations/{organization_id}/principals

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/principals

Request

Path Parameters

organization_idstring

organization_id is the organization to query principals in.

Query Parameters

principal_idsstring[]

principal_ids is the list of principals to retrieve. A maximum of 1000 princiapls are allowed in a single request.

viewstring

view allows the caller to choose the set of principal data that is returned. If unset, the request defaults to PRINCIPAL_VIEW_BASIC.

PRINCIPAL_VIEW_UNSPECIFIED: The default / unset value.
PRINCIPAL_VIEW_BASIC: Include basic metadata about the principal, but not the principal details. This will return the Id and Type only.
PRINCIPAL_VIEW_FULL: Include everything.

Response

200 - OK

principalsobject[]

Principal is the common wrapper for our different types of principals.

idstring
id is the identifier for the principal.
typestring
PrincipalType represents the possible types of principals.

PRINCIPAL_TYPE_UNSPECIFIED: PRINCIPAL_TYPE_UNSPECIFIED is the default value.

PRINCIPAL_TYPE_USER: PRINCIPAL_TYPE_USER is the user principal type.

PRINCIPAL_TYPE_SERVICE: PRINCIPAL_TYPE_SERVICE is the service principal type.

PRINCIPAL_TYPE_GROUP: PRINCIPAL_TYPE_GROUP is the group principal type.

PRINCIPAL_TYPE_INTERNAL_OPERATOR: PRINCIPAL_TYPE_INTERNAL_OPERATOR is the internal operator principal type.
userobject
UserPrincipal represents a human user of our platform.
- idstring
  id is the UUID public identifier for a user principal. It is safe to share this value with external users, and it should be how user principals are commonly identified also within our platform.
- emailstring
  email is the unique email address of this user.
- full_namestring
  full_name is the name of the user, as provided by Auth0.
- identity_typestring
  IdentityType contains the identity types for users.
  
  UNSET: UNSET is the default value, should not be used.
  
  SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.
  
  EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.
  
  SAMLP: SAMLP is the auth0 SAML provider.
  
  HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
- identity_typesstring[]
  IdentityType contains the identity types for users.
  
  UNSET: UNSET is the default value, should not be used.
  
  SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.
  
  EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.
  
  SAMLP: SAMLP is the auth0 SAML provider.
  
  HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
- subjectstring
  subject is the user ID from the authenticating IDP (e.g. Hydra).
- scim_synchronizedboolean
  scim_synchronized denotes the user principal was synchronized from a customer's IdP using SCIM.
- tfc_synchronized_atstring
  tfc_synchronized_at denotes the timestamp of when the user was synced to TFC when applicable.
serviceobject
ServicePrincipal is the HCP identity for a machine user.
- idstring
  id is the UUID identifier for this service principal.
- namestring
  name is the name for this service principal.
- resource_namestring
  resource_name is the resource name for this service principal.
- organization_idstring
  organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
- created_atstring
  created_at is when the service principal was created.
- project_idstring
  project_id is the UUID identifier of the HCP project that this project service principal belongs to.
groupobject
- resource_idstring
  resource_id is the principal ID of the group.
- resource_namestring
  resource_name is the name of the group.
- display_namestring
  display_name is the user-specified display name of the group.
- descriptionstring
  description is a description of the group.
- created_atstring
  created_at is when the group was created.
- updated_atstring
  updated_at is when the group was last updated.
- member_countinteger
- scim_synchronizedboolean
  scim_synchronized denotes the group was synchronized from an upstream IdP using SCIM.
group_idsstring[]

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

SearchPrincipals

/iam/organizations/{organization_id}/principals/search

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/principals/search

Request

Path Parameters

organization_idstring

organization_id is the ID of the organization in which the principals belong.

Body Parameters

filterobject

SearchPrincipalsFilter contains optional filter fields when making a SearchPrincipalsRequest.

search_textstring
search_text is the search text which cause the results will be filtered to principals whose name/email contains the text.
principal_typesstring[]
PrincipalType represents the possible types of principals.

PRINCIPAL_TYPE_UNSPECIFIED: PRINCIPAL_TYPE_UNSPECIFIED is the default value.

PRINCIPAL_TYPE_USER: PRINCIPAL_TYPE_USER is the user principal type.

PRINCIPAL_TYPE_SERVICE: PRINCIPAL_TYPE_SERVICE is the service principal type.

PRINCIPAL_TYPE_GROUP: PRINCIPAL_TYPE_GROUP is the group principal type.

PRINCIPAL_TYPE_INTERNAL_OPERATOR: PRINCIPAL_TYPE_INTERNAL_OPERATOR is the internal operator principal type.
exclude_members_of_group_namesstring[]

paginationobject

PaginationRequest are the parameters for a paginated list request.

page_sizeinteger
The max number of results per page that should be returned. If the number of available results is larger than page_size, a next_page_token is returned which can be used to get the next page of results in subsequent requests. A value of zero will cause page_size to be defaulted.
next_page_tokenstring
Specifies a page token to use to retrieve the next page. Set this to the next_page_token returned by previous list requests to get the next page of results. If set, previous_page_token must not be set.
previous_page_tokenstring
Specifies a page token to use to retrieve the previous page. Set this to the previous_page_token returned by previous list requests to get the previous page of results. If set, next_page_token must not be set.

Response

200 - OK

principalsobject[]

SearchPrincipalsResult is the result type contained the response of the SearchPrincipals rpc.

principal_typestring
PrincipalType represents the possible types of principals.

PRINCIPAL_TYPE_UNSPECIFIED: PRINCIPAL_TYPE_UNSPECIFIED is the default value.

PRINCIPAL_TYPE_USER: PRINCIPAL_TYPE_USER is the user principal type.

PRINCIPAL_TYPE_SERVICE: PRINCIPAL_TYPE_SERVICE is the service principal type.

PRINCIPAL_TYPE_GROUP: PRINCIPAL_TYPE_GROUP is the group principal type.

PRINCIPAL_TYPE_INTERNAL_OPERATOR: PRINCIPAL_TYPE_INTERNAL_OPERATOR is the internal operator principal type.
idstring
id is the ID of the principal.
namestring
name is the name of the principal.
emailstring
email is the email address of the principal.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateOrganizationServicePrincipalKey

/iam/organizations/{organization_id}/service-principal-keys

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/service-principal-keys

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization under which the service principal key should be created. It must be the organization of the provided service principal.

Body Parameters

principal_idstring

principal_id is the ID of the service principal for which the new service principal key should be created.

Response

200 - OK

keyobject

Key is a service principal key used to authenticate a service principal.

resource_namestring
resource_name is the resource name for this service principal key.
client_idstring
client_id is the non-secret part of the credential set.
created_atstring
created_at is when the Key resource was created.
statestring
State is the state of the key.

UNSET: UNSET is the default value. Should never be used at runtime for valid messages.

CREATING: CREATING is a key that's just been inserted in the DB, and its authN credentials are still being prepared. Will transition to ACTIVE on success.

ACTIVE: ACTIVE is a key that's been properly created and is ready to use.

DELETING: DELETING is a key that it's being deleted. It will be fully deleted once its authN credentials will have been deleted from Auth0.

client_secretstring

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteOrganizationServicePrincipalKey

/iam/organizations/{organization_id}/service-principal-keys/{client_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/service-principal-keys/{client_id}

Request

Path Parameters

organization_idstring

organization_id is the organization the service principal key belongs to.

client_idstring

client_id is client ID of the service principal key.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListOrganizationServicePrincipals

/iam/organizations/{organization_id}/service-principals

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/service-principals

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization that owns the service principals to be listed.

Query Parameters

includestring

include defines which service principals in the hirarchical level below an organization should be included in the returned list. Allowed values: UNSET, ALL, PROJECTS

UNSET: UNSET is the default value. UNSET will only include service principals at organization level.
ALL: ALL will include all service principals on all hirarchical levels under the given organization.
PROJECTS: PROJECTS includes service principals at project level in the list response.

pagination.page_sizeinteger

pagination.next_page_tokenstring

pagination.previous_page_tokenstring

Response

200 - OK

service_principalsobject[]

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateOrganizationServicePrincipal

/iam/organizations/{organization_id}/service-principals

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/service-principals

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization under which the service principal should be created.

Body Parameters

namestring

name is the customer-chosen name for this service principal.

Response

200 - OK

service_principalobject

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetOrganizationServicePrincipal

/iam/organizations/{organization_id}/service-principals/{principal_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/service-principals/{principal_id}

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization that owns the requested service principal or project.

principal_idstring

principal_id is the ID of the service principal being requested.

Response

200 - OK

service_principalobject

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

keysobject[]

Key is a service principal key used to authenticate a service principal.

resource_namestring
resource_name is the resource name for this service principal key.
client_idstring
client_id is the non-secret part of the credential set.
created_atstring
created_at is when the Key resource was created.
statestring
State is the state of the key.

UNSET: UNSET is the default value. Should never be used at runtime for valid messages.

CREATING: CREATING is a key that's just been inserted in the DB, and its authN credentials are still being prepared. Will transition to ACTIVE on success.

ACTIVE: ACTIVE is a key that's been properly created and is ready to use.

DELETING: DELETING is a key that it's being deleted. It will be fully deleted once its authN credentials will have been deleted from Auth0.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteOrganizationServicePrincipal

/iam/organizations/{organization_id}/service-principals/{principal_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/service-principals/{principal_id}

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization from which the service principal should be deleted.

principal_idstring

principal_id is the ID of the service principal to be deleted.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListSSOConfigurations

/iam/organizations/{organization_id}/sso-configurations

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/sso-configurations

Request

Path Parameters

organization_idstring

OrganizationId is the identifier of the organization.

Response

200 - OK

configurationsobject[]

typestring
SSOType is the type of SSO.

UNSET: UNSET is the default value. It should never be used at runtime for valid messages.

SAML: SAML is a SAML connection.

OIDC: OIDC is a OIDC connection stored in cloud-idp.
samlobject
- signin_urlstring
- certificatestring
  Certificate holds the signing certificate that will be used to sign all SAML assertions.
- signout_urlstring
  SignoutUrl is the optional SAML single sign-out URL for the organization. If not present, then we use the signin_url instead.
- email_domainsstring[]
- assertion_consumer_urlstring
  AssertionConsumerUrl has the Assertion Consumer URL (or Post Back in Auth0 parlance) for the IdP. This is not editable.
- entity_idstring
  EntityUrl has the name of the audience the IdP needs to set up on their side. This is not editable.
created_atstring
updated_atstring
updated_at is the last time that the configuration was modified.
default_rolestring
default_role is the default RBAC role that users joining the SSO organization should get.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateSSOConfiguration

/iam/organizations/{organization_id}/sso-configurations

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/sso-configurations

Request

Path Parameters

organization_idstring

OrganizationId is the identifier of the organization.

Body Parameters

configobject

typestring
SSOType is the type of SSO.

UNSET: UNSET is the default value. It should never be used at runtime for valid messages.

SAML: SAML is a SAML connection.

OIDC: OIDC is a OIDC connection stored in cloud-idp.
samlobject
- signin_urlstring
- certificatestring
  Certificate holds the signing certificate that will be used to sign all SAML assertions.
- signout_urlstring
  SignoutUrl is the optional SAML single sign-out URL for the organization. If not present, then we use the signin_url instead.
- email_domainsstring[]
- assertion_consumer_urlstring
  AssertionConsumerUrl has the Assertion Consumer URL (or Post Back in Auth0 parlance) for the IdP. This is not editable.
- entity_idstring
  EntityUrl has the name of the audience the IdP needs to set up on their side. This is not editable.
created_atstring
updated_atstring
updated_at is the last time that the configuration was modified.
default_rolestring
default_role is the default RBAC role that users joining the SSO organization should get.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetSSOConfiguration

/iam/organizations/{organization_id}/sso-configurations/{type}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/sso-configurations/{type}

Request

Path Parameters

organization_idstring

OrganizationId is the identifier of the organization.

typestring

Type is the type of Single Sign-On.

Response

200 - OK

configobject

typestring
SSOType is the type of SSO.

UNSET: UNSET is the default value. It should never be used at runtime for valid messages.

SAML: SAML is a SAML connection.

OIDC: OIDC is a OIDC connection stored in cloud-idp.
samlobject
- signin_urlstring
- certificatestring
  Certificate holds the signing certificate that will be used to sign all SAML assertions.
- signout_urlstring
  SignoutUrl is the optional SAML single sign-out URL for the organization. If not present, then we use the signin_url instead.
- email_domainsstring[]
- assertion_consumer_urlstring
  AssertionConsumerUrl has the Assertion Consumer URL (or Post Back in Auth0 parlance) for the IdP. This is not editable.
- entity_idstring
  EntityUrl has the name of the audience the IdP needs to set up on their side. This is not editable.
created_atstring
updated_atstring
updated_at is the last time that the configuration was modified.
default_rolestring
default_role is the default RBAC role that users joining the SSO organization should get.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteSSOConfiguration

/iam/organizations/{organization_id}/sso-configurations/{type}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/sso-configurations/{type}

Request

Path Parameters

organization_idstring

OrganizationId is the identifier of the organization.

typestring

Type is the type of Single Sign-On.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

UpdateSSOConfiguration

/iam/organizations/{organization_id}/sso-configurations/{type}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/sso-configurations/{type}

Request

Path Parameters

organization_idstring

OrganizationId is the identifier of the organization.

typestring

type is the type of Single Sign-On we are updating. This is only used for the RESTFul Gateway parameter. It must match the type in the config field. This is used due to a bug in the grpc-gateway generator that erases the field value if a field is used as a parameter. So we need to use this one instead of config.type.

Body Parameters

configobject

typestring
SSOType is the type of SSO.

UNSET: UNSET is the default value. It should never be used at runtime for valid messages.

SAML: SAML is a SAML connection.

OIDC: OIDC is a OIDC connection stored in cloud-idp.
samlobject
- signin_urlstring
- certificatestring
  Certificate holds the signing certificate that will be used to sign all SAML assertions.
- signout_urlstring
  SignoutUrl is the optional SAML single sign-out URL for the organization. If not present, then we use the signin_url instead.
- email_domainsstring[]
- assertion_consumer_urlstring
  AssertionConsumerUrl has the Assertion Consumer URL (or Post Back in Auth0 parlance) for the IdP. This is not editable.
- entity_idstring
  EntityUrl has the name of the audience the IdP needs to set up on their side. This is not editable.
created_atstring
updated_atstring
updated_at is the last time that the configuration was modified.
default_rolestring
default_role is the default RBAC role that users joining the SSO organization should get.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetPreconfigurationData

/iam/organizations/{organization_id}/sso-preconfiguration-data

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/sso-preconfiguration-data

Request

Path Parameters

organization_idstring

organization_id is the ID of the organization for which the preconfiguration data is required.

Response

200 - OK

domain_txt_verification_recordstring

domain_txt_verification_record is the expected value of the TXT ownership verification record we require organizations to add to their email domain's DNS to prove that they own/control the domain.

assertion_consumer_urlstring

AssertionConsumerUrl has the Assertion Consumer URL (or Post Back in Auth0 parlance) for the IdP.

entity_idstring

EntityUrl has the name of the audience the IdP needs to set up on their side.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetSSOType

/iam/organizations/{organization_id}/sso-type

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/sso-type

Request

Path Parameters

organization_idstring

OrganizationId is the identifier of the organization.

Response

200 - OK

typestring

SSOType is the type of SSO.

UNSET: UNSET is the default value. It should never be used at runtime for valid messages.
SAML: SAML is a SAML connection.
OIDC: OIDC is a OIDC connection stored in cloud-idp.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListUserPrincipalsByOrganization

/iam/organizations/{organization_id}/user-principals

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/user-principals

Request

Path Parameters

organization_idstring

organization_id is the UUID of an organization.

Query Parameters

pagination.page_sizeinteger

pagination.next_page_tokenstring

pagination.previous_page_tokenstring

Response

200 - OK

user_principalsobject[]

UserPrincipal represents a human user of our platform.

idstring
id is the UUID public identifier for a user principal. It is safe to share this value with external users, and it should be how user principals are commonly identified also within our platform.
emailstring
email is the unique email address of this user.
full_namestring
full_name is the name of the user, as provided by Auth0.
identity_typestring
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
identity_typesstring[]
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
subjectstring
subject is the user ID from the authenticating IDP (e.g. Hydra).
scim_synchronizedboolean
scim_synchronized denotes the user principal was synchronized from a customer's IdP using SCIM.
tfc_synchronized_atstring
tfc_synchronized_at denotes the timestamp of when the user was synced to TFC when applicable.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetUserPrincipalsByIDsInOrganization

/iam/organizations/{organization_id}/user-principals/batch-fetch

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/user-principals/batch-fetch

Request

Path Parameters

organization_idstring

organization_id is the ID of organization for users to look up

Body Parameters

idsstring[]

Response

200 - OK

user_principalsobject[]

UserPrincipal represents a human user of our platform.

idstring
id is the UUID public identifier for a user principal. It is safe to share this value with external users, and it should be how user principals are commonly identified also within our platform.
emailstring
email is the unique email address of this user.
full_namestring
full_name is the name of the user, as provided by Auth0.
identity_typestring
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
identity_typesstring[]
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
subjectstring
subject is the user ID from the authenticating IDP (e.g. Hydra).
scim_synchronizedboolean
scim_synchronized denotes the user principal was synchronized from a customer's IdP using SCIM.
tfc_synchronized_atstring
tfc_synchronized_at denotes the timestamp of when the user was synced to TFC when applicable.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetUserPrincipalByIdInOrganization

/iam/organizations/{organization_id}/user-principals/{user_principal_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/user-principals/{user_principal_id}

Request

Path Parameters

organization_idstring

organization_id is the organization_id the requested user principal belongs to.

user_principal_idstring

user_principal_id is the user ID for the requested user principal.

Response

200 - OK

user_principalobject

UserPrincipal represents a human user of our platform.

idstring
id is the UUID public identifier for a user principal. It is safe to share this value with external users, and it should be how user principals are commonly identified also within our platform.
emailstring
email is the unique email address of this user.
full_namestring
full_name is the name of the user, as provided by Auth0.
identity_typestring
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
identity_typesstring[]
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
subjectstring
subject is the user ID from the authenticating IDP (e.g. Hydra).
scim_synchronizedboolean
scim_synchronized denotes the user principal was synchronized from a customer's IdP using SCIM.
tfc_synchronized_atstring
tfc_synchronized_at denotes the timestamp of when the user was synced to TFC when applicable.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteOrganizationMembership

/iam/organizations/{organization_id}/user-principals/{user_principal_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/user-principals/{user_principal_id}

Request

Path Parameters

organization_idstring

organization_id is the ID of the organization the user principal is being deleted from.

user_principal_idstring

user_principal_id is the ID of the user principal to delete from the organization.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

VerifyDomainOwnership

/iam/organizations/{organization_id}/verify-domain-ownership

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/verify-domain-ownership

Request

Path Parameters

organization_idstring

organization_id is the ID of the organization for which domain ownership will be verified.

Body Parameters

domainstring

domain is the domain for which ownership will be verified.

Response

200 - OK

verifiedboolean

verified indicates whether or not an organization's ownership/control of a domain has been verified.

reasonstring

ReasonDomainOwnershipUnverified is the reason a request to verify an organizations's ownership/control of a domain failed.

UNSET: NOT_PROVIDED is the default value. It should never be used when a verification failed.
NO_TXT_RECORD: NO_TXT_RECORD is the reason a verification failed when a domain does not contain proof of ownership.
NO_SUCH_HOST: NO_SUCH_HOST is the reason a verification failed when the given domain does not exist.
ALREADY_IN_USE: ALREADY_IN_USE is the reason a verfication failed when the given domain is already in use by another organization.

domainstring

domain is the domain for which the ownership has been verified.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

VerifySSODomainOwnership

/iam/organizations/{organization_id}/verify-sso-domain-ownership

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/verify-sso-domain-ownership

Request

Path Parameters

organization_idstring

organization_id is the ID of the organization for which domain ownership will be verified.

Body Parameters

domainstring

domain is the domain for which ownership will be verified.

Response

200 - OK

verifiedboolean

verified indicates whether or not an organization's ownership/control of a domain has been verified.

reasonstring

ReasonDomainOwnershipUnverified is the reason a request to verify an organizations's ownership/control of a domain failed.

UNSET: NOT_PROVIDED is the default value. It should never be used when a verification failed.
NO_TXT_RECORD: NO_TXT_RECORD is the reason a verification failed when a domain does not contain proof of ownership.
NO_SUCH_HOST: NO_SUCH_HOST is the reason a verification failed when the given domain does not exist.
ALREADY_IN_USE: ALREADY_IN_USE is the reason a verfication failed when the given domain is already in use by another organization.

domainstring

domain is the domain for which the ownership has been verified.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateProjectServicePrincipalKey

/service-principal-keys

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/projects/{project_id}/service-principal-keys

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization under which the service principal key should be created. It must be the organization of the provided service principal.

project_idstring

project_id is the unique identifier (UUID) of the project under which the service principal key should be created. It must be the project_id of the provided service principal.

Body Parameters

principal_idstring

principal_id is the ID of the service principal for which the new service principal key should be created.

Response

200 - OK

keyobject

Key is a service principal key used to authenticate a service principal.

resource_namestring
resource_name is the resource name for this service principal key.
client_idstring
client_id is the non-secret part of the credential set.
created_atstring
created_at is when the Key resource was created.
statestring
State is the state of the key.

UNSET: UNSET is the default value. Should never be used at runtime for valid messages.

CREATING: CREATING is a key that's just been inserted in the DB, and its authN credentials are still being prepared. Will transition to ACTIVE on success.

ACTIVE: ACTIVE is a key that's been properly created and is ready to use.

DELETING: DELETING is a key that it's being deleted. It will be fully deleted once its authN credentials will have been deleted from Auth0.

client_secretstring

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteProjectServicePrincipalKey

/service-principal-keys/{client_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/projects/{project_id}/service-principal-keys/{client_id}

Request

Path Parameters

organization_idstring

organization_id is the organization the service principal key belongs to.

project_idstring

project_id is the project the service principal key belongs to.

client_idstring

client_id is client ID of the service principal key.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListProjectServicePrincipals

/service-principals

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/projects/{project_id}/service-principals

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization that owns the project of the service principals to be listed.

project_idstring

project_id is the unique identifier (UUID) of the project that owns the service principals to be listed. When the the project_id is provided, only the service principals for this project will be listed.

Query Parameters

pagination.page_sizeinteger

pagination.next_page_tokenstring

pagination.previous_page_tokenstring

Response

200 - OK

service_principalsobject[]

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateProjectServicePrincipal

/service-principals

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/projects/{project_id}/service-principals

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization under which the service principal should be created.

project_idstring

project_id is the unique identifier (UUID) of the project that owns the created service principal.

Body Parameters

namestring

name is the customer-chosen name for this service principal.

Response

200 - OK

service_principalobject

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetProjectServicePrincipal

/service-principals/{principal_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/projects/{project_id}/service-principals/{principal_id}

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization that owns the requested service principal or project.

project_idstring

project_id is the unique identifier (UUID) of the project that under which the service principal should be created.

principal_idstring

principal_id is the ID of the service principal being requested.

Response

200 - OK

service_principalobject

ServicePrincipal is the HCP identity for a machine user.

idstring
id is the UUID identifier for this service principal.
namestring
name is the name for this service principal.
resource_namestring
resource_name is the resource name for this service principal.
organization_idstring
organization_id is the UUID identifier of the HCP organization that this service principal belongs to.
created_atstring
created_at is when the service principal was created.
project_idstring
project_id is the UUID identifier of the HCP project that this project service principal belongs to.

keysobject[]

Key is a service principal key used to authenticate a service principal.

resource_namestring
resource_name is the resource name for this service principal key.
client_idstring
client_id is the non-secret part of the credential set.
created_atstring
created_at is when the Key resource was created.
statestring
State is the state of the key.

UNSET: UNSET is the default value. Should never be used at runtime for valid messages.

CREATING: CREATING is a key that's just been inserted in the DB, and its authN credentials are still being prepared. Will transition to ACTIVE on success.

ACTIVE: ACTIVE is a key that's been properly created and is ready to use.

DELETING: DELETING is a key that it's being deleted. It will be fully deleted once its authN credentials will have been deleted from Auth0.

project_idstring

project_id is the unique identifier (UUID) of the project that owns the requested service principal.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteProjectServicePrincipal

/service-principals/{principal_id}

https://api.cloud.hashicorp.com/iam/2019-12-10/organizations/{organization_id}/projects/{project_id}/service-principals/{principal_id}

Request

Path Parameters

organization_idstring

organization_id is the unique identifier (UUID) of the organization from which the service principal should be deleted.

project_idstring

project_id is the unique identifier (UUID) of the project that owns the requested service principal.

principal_idstring

principal_id is the ID of the service principal to be deleted.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

Ping

/iam/ping

https://api.cloud.hashicorp.com/iam/2019-12-10/ping

Request

No request data.

Response

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

CreateUserPrincipal

/iam/user-principals

https://api.cloud.hashicorp.com/iam/2019-12-10/user-principals

Request

Body Parameters

accept_tosboolean

accept_privacy_policyboolean

Response

200 - OK

user_principalobject

UserPrincipal represents a human user of our platform.

idstring
id is the UUID public identifier for a user principal. It is safe to share this value with external users, and it should be how user principals are commonly identified also within our platform.
emailstring
email is the unique email address of this user.
full_namestring
full_name is the name of the user, as provided by Auth0.
identity_typestring
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
identity_typesstring[]
IdentityType contains the identity types for users.

UNSET: UNSET is the default value, should not be used.

SOCIAL_GITHUB: SOCIAL_GITHUB is the GitHub Social login provider.

EMAIL_PASSWORD: EMAIL_PASSWORD is the auth0 email/password database provider.

SAMLP: SAMLP is the auth0 SAML provider.

HASHICORP_SSO: HASHICORP_SSO is the HashiCorp SSO provider.
subjectstring
subject is the user ID from the authenticating IDP (e.g. Hydra).
scim_synchronizedboolean
scim_synchronized denotes the user principal was synchronized from a customer's IdP using SCIM.
tfc_synchronized_atstring
tfc_synchronized_at denotes the timestamp of when the user was synced to TFC when applicable.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

GetGroup

/iam/{resource_name}

https://api.cloud.hashicorp.com/iam/2019-12-10/{resource_name}

Request

Path Parameters

resource_namestring

resource_name is the resource name of the group. iam/organization/<org_id>/group/<group_id>

Response

200 - OK

groupobject

resource_idstring
resource_id is the principal ID of the group.
resource_namestring
resource_name is the name of the group.
display_namestring
display_name is the user-specified display name of the group.
descriptionstring
description is a description of the group.
created_atstring
created_at is when the group was created.
updated_atstring
updated_at is when the group was last updated.
member_countinteger
scim_synchronizedboolean
scim_synchronized denotes the group was synchronized from an upstream IdP using SCIM.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

DeleteGroup

/iam/{resource_name}

https://api.cloud.hashicorp.com/iam/2019-12-10/{resource_name}

Request

Path Parameters

resource_namestring

resource_name is the resource name of the group. iam/organization/<org_id>/group/<group_id>.

Response

200 - OK

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

UpdateGroup

/iam/{resource_name}

https://api.cloud.hashicorp.com/iam/2019-12-10/{resource_name}

Request

Path Parameters

resource_namestring

resource_name is the resource name of the group. iam/organization/<org_id>/group/<group_id>

Body Parameters

groupobject

resource_idstring
resource_id is the principal ID of the group.
resource_namestring
resource_name is the name of the group.
display_namestring
display_name is the user-specified display name of the group.
descriptionstring
description is a description of the group.
created_atstring
created_at is when the group was created.
updated_atstring
updated_at is when the group was last updated.
member_countinteger
scim_synchronizedboolean
scim_synchronized denotes the group was synchronized from an upstream IdP using SCIM.

update_maskstring

update_mask is the list of group fields being updated.

Response

200 - OK

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

UpdateGroup2

/iam/{resource_name}

https://api.cloud.hashicorp.com/iam/2019-12-10/{resource_name}

Request

Path Parameters

resource_namestring

resource_name is the resource name of the group. iam/organization/<org_id>/group/<group_id>

Query Parameters

update_maskstring

update_mask is the list of group fields being updated.

Body Parameters

resource_idstring

resource_id is the principal ID of the group.

resource_namestring

resource_name is the name of the group.

display_namestring

display_name is the user-specified display name of the group.

descriptionstring

description is a description of the group.

created_atstring

created_at is when the group was created.

updated_atstring

updated_at is when the group was last updated.

member_countinteger

scim_synchronizedboolean

scim_synchronized denotes the group was synchronized from an upstream IdP using SCIM.

Response

200 - OK

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

ListGroupMembers

/iam/{resource_name}/members

https://api.cloud.hashicorp.com/iam/2019-12-10/{resource_name}/members

Request

Path Parameters

resource_namestring

resource_name is the resource name of the group. iam/organization/<org_id>/group/<group_id>.

Query Parameters

pagination.page_sizeinteger

pagination.next_page_tokenstring

pagination.previous_page_tokenstring

Response

200 - OK

membersobject[]

principal_typestring
idstring
id is the ID of the principal.
namestring
name is the name of the principal.
emailstring
email is the email address of the principal.

paginationobject

PaginationResponse is the response holding the page tokens for a paginated list response.

next_page_tokenstring
This token allows you to get the next page of results for list requests. If the number of results is larger than page_size, use the next_page_token as a value for the query parameter next_page_token in the next request. The value will become empty when there are no more pages.
previous_page_tokenstring
This token allows you to get the previous page of results for list requests. If the number of results is larger than page_size, use the previous_page_token as a value for the query parameter previous_page_token in the next request. The value will become empty when there are no more pages.

groupobject

resource_idstring
resource_id is the principal ID of the group.
resource_namestring
resource_name is the name of the group.
display_namestring
display_name is the user-specified display name of the group.
descriptionstring
description is a description of the group.
created_atstring
created_at is when the group was created.
updated_atstring
updated_at is when the group was last updated.
member_countinteger
scim_synchronizedboolean
scim_synchronized denotes the group was synchronized from an upstream IdP using SCIM.

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

UpdateGroupMembers

/iam/{resource_name}/members

https://api.cloud.hashicorp.com/iam/2019-12-10/{resource_name}/members

Request

Path Parameters

resource_namestring

resource_name is the resource name of the group. iam/organization/<org_id>/group/<group_id>.

Body Parameters

member_principal_ids_to_addstring[]

member_principal_ids_to_removestring[]

Response

200 - OK

Default Error Response

codeinteger

messagestring

detailsobject[]

An arbitrary serialized message. Visit the protobufAny documentation for more information.

@typestring
A URL that describes the type of the serialized message.

​​/​​iam​​/​​{parent_resource_name_1}​

​​/​​iam​​/​​{parent_resource_name}​

​​/​​{parent_resource_name_1}​​/​​keys

​​/​​{parent_resource_name}​​/​​keys

​​/​​{parent_resource_name}​​/​​workload-identity-providers

​​/​​{provider.resource_name}

​​/​​{resource_name_1}

​​/​​{resource_name_2}

​​/​​{resource_name_3}

​​/​​{resource_name_4}

​​/​​{resource_name}

​​/​​{resource_name}​​/​​exchange-token

​​/​​iam​​/​​accept-invitation

​​/​​iam​​/​​caller-identity

​​/​​iam​​/​​iam​

​​/​​iam​​/​​invitations​

​​/​​iam​​/​​me

​​/​​iam​​/​​me​

​​/​​iam​​/​​organizations​

​​/​​service-principal-keys

​​/​​service-principal-keys​​/​​{client_id}

​​/​​service-principals

​​/​​service-principals​​/​​{principal_id}

​​/​​iam​​/​​ping

​​/​​iam​​/​​user-principals

​​/​​iam​​/​​{resource_name}

​​/​​iam​​/​​{resource_name}​

Resources

Resources

​​/​​iam​​/​​{parent_resource_name_1}​

​​/​​iam​​/​​{parent_resource_name}​

​​/​​{parent_resource_name_1}​​/​​keys

​​/​​{parent_resource_name}​​/​​keys

​​/​​{parent_resource_name}​​/​​workload-identity-providers

​​/​​{provider.resource_name}

​​/​​{resource_name_1}

​​/​​{resource_name_2}

​​/​​{resource_name_3}

​​/​​{resource_name_4}

​​/​​{resource_name}

​​/​​{resource_name}​​/​​exchange-token

​​/​​iam​​/​​accept-invitation

​​/​​iam​​/​​caller-identity

​​/​​iam​​/​​iam​

​​/​​iam​​/​​invitations​

​​/​​iam​​/​​me

​​/​​iam​​/​​me​

​​/​​iam​​/​​organizations​

​​/​​service-principal-keys

​​/​​service-principal-keys​​/​​{client_id}

​​/​​service-principals

​​/​​service-principals​​/​​{principal_id}

​​/​​iam​​/​​ping

​​/​​iam​​/​​user-principals

​​/​​iam​​/​​{resource_name}

​​/​​iam​​/​​{resource_name}​

Resources

Operations

​List​Service​Principals2

Request

Path Parameters

Query Parameters

Response

200 - OK200 - OK

Default Error ResponseDefault Error Response

​Create​Service​Principal2

Request

Path Parameters

Body Parameters

Response

200 - OK200 - OK

Default Error ResponseDefault Error Response

​List​Service​Principals

Request

Path Parameters

Query Parameters

Response

200 - OK200 - OK

Default Error ResponseDefault Error Response

​Create​Service​Principal

/iam/{parent_resource_name_1}

/iam/{parent_resource_name}

/{parent_resource_name_1}/keys

/{parent_resource_name}/keys

/{parent_resource_name}/workload-identity-providers

/{provider.resource_name}

/{resource_name_1}

/{resource_name_2}

/{resource_name_3}

/{resource_name_4}

/{resource_name}

/{resource_name}/exchange-token

/iam/accept-invitation

/iam/caller-identity

/iam/iam

/iam/invitations

/iam/me

/iam/me

/iam/organizations

/service-principal-keys

/service-principal-keys/{client_id}

/service-principals

/service-principals/{principal_id}

/iam/ping

/iam/user-principals

/iam/{resource_name}

/iam/{resource_name}

/iam/{parent_resource_name_1}

/iam/{parent_resource_name}

/{parent_resource_name_1}/keys

/{parent_resource_name}/keys

/{parent_resource_name}/workload-identity-providers

/{provider.resource_name}

/{resource_name_1}

/{resource_name_2}

/{resource_name_3}

/{resource_name_4}

/{resource_name}

/{resource_name}/exchange-token

/iam/accept-invitation

/iam/caller-identity

/iam/iam

/iam/invitations

/iam/me

/iam/me

/iam/organizations

/service-principal-keys

/service-principal-keys/{client_id}

/service-principals

/service-principals/{principal_id}

/iam/ping

/iam/user-principals

/iam/{resource_name}

/iam/{resource_name}

ListServicePrincipals2

200 - OK

Default Error Response

CreateServicePrincipal2

200 - OK

Default Error Response

ListServicePrincipals

200 - OK

Default Error Response

CreateServicePrincipal

200 - OK

Default Error Response

CreateServicePrincipalKey2

200 - OK

Default Error Response

CreateServicePrincipalKey

200 - OK

Default Error Response

ListWorkloadIdentityProvider

200 - OK

Default Error Response

CreateWorkloadIdentityProvider

200 - OK

Default Error Response

UpdateWorkloadIdentityProvider

200 - OK