Overview
This guide outlines the automated customer creation process using our MSP API. The integration enables Managed Service Providers (MSPs) to programmatically create customers, generate onboarding resources, and establish integrations without manual intervention.
Prerequisites: Obtaining API Key
Customer Creation API Flow Architecture
The customer creation process follows a three-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 & Headers
All API calls require proper authentication headers:
X-API-Key: <your-api-key>
Content-Type: application/json
Critical For Step 2, you must include the Wiv impersonation header X-Wiv-Impersonated-Tenant-Id: <customer_id> This header allows the MSP to perform action on behalf of the newly created customer
Step 1: Create Customer
Endpoint: /msp/customers
Description: Creates a new customer organization in the system.
Method: [POST]
Headers
X-API-Key: <your-api-key> Content-Type: application/json
Body
{
"name": "Wiv-MSP-Customer"
}Response```
{
"data": {
"name": "Wiv-MSP-Customer",
"customer_id": "f7016a5c-42fc-46d5-a344-3e63d756f4f5"
}
}Important Save the customer_id field from the response This becomes your customer_id for subsequent API calls
Step 2: Generate AWS Onboarding Link
Endpoint: /onboarding/aws/cloudformation-link
Description: Creates the AWS CloudFormation template and onboarding resources for the customer.
Method: [POST]
Headers
X-API-Key: <your-api-key> Content-Type: application/json X-Wiv-Impersonated-Tenant-Id: <customer_id>
Body
{
"account_type": "payer",
"cur_config_type": "cur"
}Response
{
"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."
}```
Important Save the external_id field from the response This becomes your external_id for subsequent API calls
.
Step 3: Create Customer Integration
Endpoint: /msp/customers/<customer_id>/integrations
Description: Establishes the integration configuration for the customer using the onboarding parameters
Method: [POST]
Headers
X-API-Key: <your-api-key> Content-Type: application/json
Body (AWS)```
{
"type": "AWS",
"name": "<Customer_Name>-AWS",
"integration_secret": {
"role_arn": "arn:aws:iam::123456789012:role/WivAccessRole", "external_id": <external_id>
}
}``` Body (GCP)`
{
"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-dummy-project-123456",
"private_key_id": "abcd1234567890abcdef1234567890abcdef12", "private_key": "-----BEGIN PRIVATE KEY-----
\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC8Q7HgL9x2Z3Vm\n[DUMMY
PRIVATE KEY - NOT REAL]\nThis is just placeholder text for a dummy private key.\nDo not use this in production or for any real authentication.\n-----END PRIVATE KEY-----",
"client_email": "dummy-service-account@my-dummy
project-123456.iam.gserviceaccount.com",
"client_id": "123456789012345678901",
"auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x_509_cert_url": "https://www.googleapis.com/oauth2/v1/ certs",
"client_x_509_cert_url": "https://www.googleapis.com/robot/v1/ metadata/x509/dummy-service-account%40my-dummy
project-123456.iam.gserviceaccount.com",
"universe_domain": "googleapis.com"
}
}Response
```
{
"data": {
"customer_id": <Customer_ID>,
"customer_integration": {
"external_id": "-",
"integration_id": <Integration_ID>,
"is_virtual": false,
"metadata": {},
"mode": "STANDARD",
"name": "<Customer_Name>-AWS",
"tenant_id": "c518e9ec-e9d1-4e9a-92ce-9591a26bb04e", "timestamp": "2025-06-19 13:12:33.599888",
"type": "AWS"
},
"customer_name": "Wiv-MSP-Customer",
"shared_resource": {
"last_published": "2025-06-19-13:12:33",
"last_update_time": "2025-06-19-13:12:33",
"shared_resource_data": {
"integration_id": "f87614a2-acda-480f-9ecd-897f35b427a8" },
"shared_resource_id": "bd9c567a-e151-46f0-90fd-7b111093c573", "shared_resource_recipients": {
"process_all": false,
"values": [
<MSP_ID>
]
},
"shared_resource_type": "integration",
"tenant_id": <Customer_ID>
}
}
}```
Step 4 (Optional): Add Users to Customer
Endpoint: /msp/customers/<customer_id>/users
Description: Adds users to the newly created customer organization with specified roles.
Method: [POST]
Headers
X-API-Key: <your-api-key> Content-Type: application/json
```
Request
{
"user_emails": [
"justin@wiv.ai",
"doti@wiv.ai"
],
"role": "MSP-Admin"
}```
Response
{
"data": {
"added_users": [
{
"email": “justin@wiv.ai",
"role": "MSP-Admin",
"user_id": "b07457bc-96cb-4457-852f-7a3b235e0829" }
],
"customer_id": "f0d2b747-3036-4261-91a9-71b4ceb0b446", "customer_name": "Wiv-MSP-Customer",
"failed_users": [
{
"email": "doti@wiv.ai",
"reason": "User not found"
}
],
"summary": {
"failed": 1,
"successfully_added": 1,
"total_requested": 2
}
}
}```
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article