Prerequisites: Obtaining an API Key
Flow Overview
The customer creation process follows a four-step sequence:
- Customer Creation — Establish the customer organization
- Onboarding Link Generation — Create AWS CloudFormation resources
- Integration Setup — Configure customer-specific integrations
- Add Users (optional) — Add users to the newly created customer
Authentication
All API calls require these headers:
X-API-Key: <your-api-key>
Content-Type: application/json
For Step 2, you must include the impersonation header:X-Wiv-Impersonated-Tenant-Id: <customer_id>This allows the MSP to perform actions on behalf of the newly created customer.
Step 1: Create Customer
Endpoint: POST /msp/customers
Headers
X-API-Key: <your-api-key>
Content-Type: application/json
{
"name": "Wiv-MSP-Customer"
}
{
"data": {
"name": "Wiv-MSP-Customer",
"customer_id": "f7016a5c-42fc-46d5-a344-3e63d756f4f5"
}
}
Save the customer_id from the response — it is required for all subsequent API calls.
Step 2: Generate AWS Onboarding Link
Endpoint: POST /onboarding/aws/cloudformation-link
Headers
X-API-Key: <your-api-key>
Content-Type: application/json
X-Wiv-Impersonated-Tenant-Id: <customer_id>
{
"account_type": "payer",
"cur_config_type": "cur"
}
{
"data": {
"cloudformation_url": "https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=...",
"pre_signed_url": "<stack-template-file>",
"external_id": "unique-external-identifier"
},
"message": "CloudFormation Link created successfully."
}
Save the external_id from the response — it is required in Step 3.
Step 3: Create Customer Integration
Endpoint: POST /msp/customers/<customer_id>/integrations
Headers
X-API-Key: <your-api-key>
Content-Type: application/json
{
"type": "AWS",
"name": "<Customer_Name>-AWS",
"integration_secret": {
"role_arn": "arn:aws:iam::123456789012:role/WivAccessRole",
"external_id": "<external_id>"
}
}
{
"type": "GCP",
"name": "<Customer_Name>-GCP",
"integration_secret": {
"project_id": "<billing_project_id>",
"billing_dataset_name": "<billing_dataset_name>",
"billing_table_name": "<billing_table_name>",
"service_account_key_file": {
"type": "service_account",
"project_id": "my-project-123456",
"private_key_id": "abcd1234...",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
"client_email": "service-account@project.iam.gserviceaccount.com",
"client_id": "123456789",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token"
}
}
}
{
"data": {
"customer_id": "<customer_id>",
"customer_integration": {
"integration_id": "<integration_id>",
"name": "<Customer_Name>-AWS",
"type": "AWS",
"mode": "STANDARD",
"timestamp": "2025-06-19 13:12:33.599888"
},
"customer_name": "Wiv-MSP-Customer"
}
}
Step 4 (Optional): Add Users
Endpoint: POST /msp/customers/<customer_id>/users
Headers
X-API-Key: <your-api-key>
Content-Type: application/json
{
"user_emails": ["user@example.com"],
"role": "MSP-Admin"
}
{
"data": {
"added_users": [
{ "email": "user@example.com", "role": "MSP-Admin", "user_id": "b07457bc-..." }
],
"failed_users": [
{ "email": "other@example.com", "reason": "User not found" }
],
"summary": {
"failed": 1,
"successfully_added": 1,
"total_requested": 2
},
"customer_id": "f0d2b747-...",
"customer_name": "Wiv-MSP-Customer"
}
}
