Method: tenants.create

Full name: projects.locations.instances.tenants.create

Provisions a new tenant under the specified partner/MSSP parent resource.

Behavior

  • The API returns a google.longrunning.Operation. The client must poll this operation (using GetOperation in the operations service) to monitor the provisioning progress.
  • The operation's metadata is of type TenantMetadata. The client should inspect creationWorkflowStatus (of type WorkflowState) in the metadata to determine the workflow status.
  • If the provisioning workflow fails or encounters an issue requiring intervention, the operation's done field remains false (the operation is not successfully completion-finished), and the creationWorkflowStatus transitions to ERROR.
  • If the tenant's displayName, customerCode, and frontendPathConfigs match those of an existing tenant, the API behaves as a retry of the provisioning workflow:
    • If the existing provisioning workflow has already completed (WorkflowState is FINISHED), the API returns ALREADY_EXISTS.
    • If the existing workflow is in a retryable state (e.g., ERROR or CANCELLED), it retries the creation workflow.
  • If the tenant's parameters (e.g., displayName or frontendPathConfigs) differ from the existing tenant under the same customerCode, the API returns ALREADY_EXISTS.

Error Scenarios

PERMISSION_DENIED
  • The caller is not authorized or recognized as a partner (MSSP).
  • The caller does not have the billing.resourceAssociations.create permission on the specified billingAccount.
INVALID_ARGUMENT
  • The request is missing the tenant field.
  • The tenant's billingAccount or tenantGcpProject is missing or invalid.
  • The displayName or customerCode (tenant ID) violates validation constraints.
  • The authMethod is invalid, unspecified, or unsupported.
  • The retentionDuration is invalid or unspecified.
  • The GCP project format is invalid, or the project number is negative.
  • The validation of frontendPathConfigs fails.
  • The provisioningFlow specification is invalid.
ALREADY_EXISTS
  • The tenant with the specified customerCode has already been fully provisioned.
  • The tenant is already associated with another GCP project.
  • The provided GCP project is already associated with another customer or tenant.
FAILED_PRECONDITION
  • Multiple active SecOps contracts are found for the specified billingAccount.
  • The requested data retention duration does not match the data retention duration specified in the contract.
  • Tenant GCP project is not same as the billing account in the SecOps contract.
  • For v1alpha, BACKSTORY_API_PARITY flow is used, but active SecOps contracts exist for the billingAccount (the client must use the TENANT_ATTRIBUTION flow instead).
  • The customer SecOps contract is not of type MANAGED_SECURITY_SERVICE_PROVIDER.

HTTP request

POST https://{endpoint}/v1alpha/{parent}/tenants

Where {endpoint} is one of the supported service endpoints.

Path parameters

Parameters
parent

string

Required. Resource name of the Partner Format: projects/{project}/locations/{location}/instances/{instanceId}

Request body

The request body contains an instance of Tenant.

Response body

If successful, the response body contains a newly created instance of Operation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/chronicle
  • https://www.googleapis.com/auth/chronicle.readonly

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • chronicle.tenants.create

Requires the following IAM permission on the tenantGcpProject resource:

  • chronicle.instances.update

For more information, see the IAM documentation.