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: Generate Your API Key
Before using the MSP API, you need to create a Tenant API key in the Wiv Platform. Step 1: Access API Keys
1 Click your avatar in the top-right corner of the Wiv Platform
2 Choose API Keys from the dropdown menu
Step 2: Create New API Key
1 Press the New API key button
2 Pick an expiration period
3 Click Create
Step 3: Secure Your API Key
1 Copy the API key that appears immediately
2 Store it securely - you will not be able to reveal it again
3 This key will be used in the X-API-Key: <your-api-key> header for all API calls
Important Security Note: Treat your API key like a password. Store it in a secure credential management system and never commit it to version control.
Customer Creation API Flow Architecture
The customer creation process follows a three-step sequence:
1. Customer Creation** - Establish the customer organization
2. Onboarding Link Generation** - Create AWS CloudFormation resources
3. Integration Setup - Configure customer-specific integrations
4. 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 actions on behalf of the newly created customer.
Step 1: Create Customer
Endpoint: [POST] /msp/customers
Creates a new customer organization in the system.
Headers
X-API-Key: <your-api-key> Content-Type: application/json
```
Body
```
{
"name": "Wiv-MSP-Customer"
}```
Response
```
{
"data": {
"name": "Wiv-MSP-Customer",
"org_id": "f7016a5c-42fc-46d5-a344-3e63d756f4f5"
}
}```
Important: Save the org_id field from the response - this becomes your customer_id for subsequent API calls.
Step 2: Generate AWS Onboarding Link
Creates the AWS CloudFormation template and onboarding resources for the customer. Endpoint: POST /onboarding/aws/cloudformation-link
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: POST /msp/customers/<customer_id>/integrations
Establishes the integration configuration for the customer using the onboarding parameters.
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: [POST] /msp/customers/<customer_id>/users
Adds users to the newly created customer organization with specified roles.
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