Upload Developer Cloud IDs Using the Harness SEI API
Overview
This page explains how to add or update developer identities using cloud IDs, provides best practices for integrating with external systems, and includes troubleshooting information to validate developer data before applying changes.
In some cases, SEI cannot automatically fetch user details such as emails, cloud IDs, and account IDs, from source integrations due to API restrictions or security limitations. This helps you:
- Add or update developer cloud IDs and emails.
- Map developer contributions accurately in SEI 2.0 from integrations where Harness SEI cannot fetch user records.
- Correct identity mismatches for accurate metric reporting.
To ensure accurate identity mapping, SEI provides two options:
-
Developer Identity API (JSON-based upload): Add or update identities via API calls.
-
CSV Upload API (File-based upload): Bulk upload identities using a CSV file.
New Endpoint Method Notes GET /v2/developers/identitiesGETRetrieve developer identities (JSON) with filtering, sorting, and pagination. GET /v2/developers/identitiesGETDownload all developer identities as CSV (text/csv).
For a complete list of endpoints and schema definitions, see the Harness API reference documentation.
Developer Identity API
Use the Developer Identity API in the following scenarios:
- Your integration (e.g. Bitbucket Cloud / GitLab Cloud etc) does not expose user identity APIs.
- You want to bulk override or correct developer identity mappings in SEI.
- You need to pre-populate developer identities during onboarding to reduce manual review.
- Current (v2)
- Previous
- JSON Endpoint:
PATCH /v2/developers/identities - CSV Endpoint:
PATCH /v2/developers/identities(multipart/form-data) - Authentication: Requires an API key with
developer_records:writescope.
Add or update developer identities (JSON or CSV). Simplified resource-based URI replaces /cloud-ids and /cloud-ids/upload.
If you are using JSON:
curl -X PATCH \
'https://app.harness.io/prod1/sei/api/v2/developers/identities' \
-H "accept: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '[
{
"email": "developer@example.com",
"integrationId": 123,
"identity": "bitbucket-user-123"
}
]'
If you are using a CSV file:
curl -X PATCH \
'https://app.harness.io/prod1/sei/api/v2/developers/identities' \
-H "x-api-key: <YOUR_API_KEY>" \
-F 'file=@"/PATH/Downloads/sample_developer.csv"'
- JSON Endpoint:
POST /v2/developers/cloud-ids - CSV Endpoint:
POST /v2/developers/cloud-ids/upload
Request Format
Headers
| Header | Value |
|---|---|
| X-Api-Key | <SEI API token> |
| Content-Type | application/json |
Payload Example
{
"integrationUsers": [
{
"email": "developer@example.com",
"applicationType": "BITBUCKET_CLOUD",
"cloudId": "dev123-cloud"
},
{
"email": "jane.doe@example.com",
"applicationType": "CUSTOM",
"cloudId": "jane.doe-internal"
}
]
}
Fields
| Field | Type | Required | Description |
|---|---|---|---|
email | String | Yes | Developer’s primary email address. Used for identity correlation. |
applicationType | String | Yes | Source system identifier (e.g., GITHUB, GITLAB_CLOUD, BITBUCKET_SERVER, HARNESS_CODE, CUSTOM). |
cloudId | String | Yes | The unique user identifier from the integration (e.g., username, account ID). |
Example cURL request
curl --location 'https://<sei-host>/v2/developers/cloud-ids' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: pat.xyz' \
--data-raw '{
"integrationUsers": [
{
"email": "aaron.phillips@company.com",
"applicationType": "CUSTOM",
"cloudId": "phillips.aaron-api1"
}
]
}'
Response
Success (200 OK)
{
"status": "success",
"message": "Developer identities updated successfully."
}
Failure (400/401)
{
"status": "error",
"message": "Invalid payload or missing authorization."
}
CSV Upload API (File-based)
Use the CSV Upload API in the following scenarios:
- You want to bulk add or update developer identities from a CSV file instead of sending JSON payloads.
- You need to migrate a large set of developer records during onboarding or system setup.
- You want to correct or override multiple developer mappings at once.
- Your integration or workflow produces CSV reports with developer identifiers that can be directly uploaded.
- Current (v2)
- Previous
- Endpoint:
PATCH /v2/developers/identities - Authentication: Requires an API key with
developer_records:writescope.
Request Format
Use Content-Type: multipart/form-data to upload a CSV file.
Example cURL request
curl -X PATCH \
'https://app.harness.io/prod1/sei/api/v2/developers/identities' \
-H "x-api-key: <YOUR_API_KEY>" \
-F 'file=@"/PATH/Downloads/sample_developer.csv"'
Response
Success (200 OK)
{
"status": "success",
"message": "CSV processed and developer identities updated successfully."
}
Failure (400/401)
{
"status": "error",
"message": "Invalid file format or missing authorization."
}
- Endpoint:
POST /v2/developers/cloud-ids/upload - Authentication: Requires an API key with
developer_records:writescope. - Multipart form-data with CSV file upload.
Request Format
Headers
| Header | Value |
|---|---|
| Authorization | Bearer <SEI API token> |
| Content-Type | multipart/form-data (auto) |
Example cURL request
curl --location 'https://<sei-cluster-base-url>/v2/developers/cloud-ids/upload' \
--header 'Authorization: pat.xyz' \
--form 'file=@"/PATH/Downloads/sample_developer.csv"'
Response
Success (200 OK)
{
"status": "success",
"message": "CSV processed and developer identities updated successfully."
}
Failure (400/401)
{
"status": "error",
"message": "Invalid file format or missing authorization."
}
Best practices
- The developers in your organization should use consistent emails across integrations to improve automatic correlation.
- If your organization has additional security restrictions that block the SEI system from fetching user identity details, we recommend automating periodic syncs of developer identities into SEI via the API.
- The team managers or admins should periodically review developer mappings in the SEI UI to ensure accurate attribution of developer effort in the metrics.