Customer Members API Reference

AVAILABLE

The Customer Members API manages project-scoped application end-user identities, external user mappings, and per-member FinOps spending limits.


1. Create a Customer Member #

Creates a new Customer Member inside a specified Project workspace.

  • Method: POST
  • Route: /v1/organizations/{orgID}/projects/{projectID}/members
  • Authentication: Bearer Token (Portal User JWT with members.create OR Project Service Token with members.write)

Request Headers #

HeaderTypeDescription
AuthorizationstringBearer <TOKEN>
Content-Typestringapplication/json

Request Body #

FieldTypeRequiredDescription
namestringYesHuman-readable label for the member.
emailstringYesContact or notification email (unique within the project).
external_user_idstringNoAuthoritative external user identifier (e.g. emp_101).
statusstringNoactive (default) or inactive.
daily_budget_amountnumberNoMaximum daily spending limit in USD.
monthly_budget_amountnumberNoMaximum monthly spending limit in USD.
budget_currencystringNoCurrency code (default: USD).

Example Request (curl) #

bash
curl -X POST "https://api.naagmani.com/v1/organizations/org_acme_corp/projects/proj_support_bot/members" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rahul Sharma",
    "email": "rahul.sharma@acme.com",
    "external_user_id": "emp_101",
    "status": "active",
    "daily_budget_amount": 25.00,
    "monthly_budget_amount": 250.00,
    "budget_currency": "USD"
  }'

Example Request (TypeScript) #

typescript
const response = await fetch(
  process.env.NAAGMANI_CONTROL_PLANE_URL + '/v1/organizations/<orgID>/projects/<projectID>/members',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.NAAGMANI_MANAGEMENT_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({"name":"Example Member","email":"member@example.com","external_user_id":"customer-101","status":"active"}),
  },
);
if (!response.ok) throw new Error('HTTP ' + response.status);
console.log(await response.json());

Response (201 Created) #

json
{
  "id": "mbr_01J8K3M90A7B2C3D4E5F6G7H8J",
  "organization_id": "org_acme_corp",
  "project_id": "proj_support_bot",
  "name": "Rahul Sharma",
  "email": "rahul.sharma@acme.com",
  "external_user_id": "emp_101",
  "status": "active",
  "daily_budget_amount": 25.0,
  "monthly_budget_amount": 250.0,
  "budget_currency": "USD",
  "created_at": "2026-10-13T20:00:00Z",
  "updated_at": "2026-10-13T20:00:00Z"
}

2. List Project Customer Members #

Retrieves a paginated list of Customer Members belonging to a project workspace.

  • Method: GET
  • Route: /v1/organizations/{orgID}/projects/{projectID}/members
  • Authentication: Bearer Token (members.read)

Query Parameters #

ParameterTypeDefaultDescription
limitinteger50Maximum number of items to return (1–100).
offsetinteger0Number of items to skip.
querystring-Case-insensitive search filter across name, email, and external_user_id.

Example Request (curl) #

bash
curl -X GET "https://api.naagmani.com/v1/organizations/org_acme_corp/projects/proj_support_bot/members?limit=20&offset=0" \
  -H "Authorization: Bearer <TOKEN>"

Response (200 OK) #

json
{
  "data": [
    {
      "id": "mbr_01J8K3M90A7B2C3D4E5F6G7H8J",
      "project_id": "proj_support_bot",
      "name": "Rahul Sharma",
      "email": "rahul.sharma@acme.com",
      "external_user_id": "emp_101",
      "status": "active",
      "monthly_budget_amount": 250.0
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

3. Get Member by ID #

  • Method: GET
  • Route: /v1/organizations/{orgID}/projects/{projectID}/members/{memberID}
  • Authentication: Bearer Token (members.read)

4. Update Member Details #

  • Method: PATCH
  • Route: /v1/organizations/{orgID}/projects/{projectID}/members/{memberID}
  • Authentication: Bearer Token (members.write)

Request Body #

json
{
  "name": "Rahul Sharma (Lead)",
  "status": "active",
  "daily_budget_amount": 35.0,
  "monthly_budget_amount": 300.0
}

5. Member FinOps Budget Management #

Get Member Budget #

  • Method: GET
  • Route: /v1/organizations/{orgID}/projects/{projectID}/members/{memberID}/budget

Update Member Budget #

  • Method: PUT or PATCH
  • Route: /v1/organizations/{orgID}/projects/{projectID}/members/{memberID}/budget

Request Body #

json
{
  "daily_budget_amount": 50.0,
  "monthly_budget_amount": 500.0,
  "budget_currency": "USD"
}

Clear / Unset Member Budget #

  • Method: DELETE
  • Route: /v1/organizations/{orgID}/projects/{projectID}/members/{memberID}/budget

Removes individual limits, reverting the member to standard project-level budget inheritance.


6. Delete Customer Member #

  • Method: DELETE
  • Route: /v1/organizations/{orgID}/projects/{projectID}/members/{memberID}
  • Authentication: Bearer Token (members.write)
  • Response: 204 No Content

7. Common Error Responses #

HTTP StatusError CodeCause & Remediation
400 Bad RequestVALIDATION_ERRORMissing required fields or negative budget amounts.
403 ForbiddenPROJECT_ACCESS_DENIEDCaller lacks ProjectAccessAssignment to this project.
403 ForbiddenENTITLEMENT_LIMIT_EXCEEDEDOrganization seat capacity (max_members) exceeded on Free tier.
404 Not FoundMEMBER_NOT_FOUNDMember ID does not exist in this project.
409 ConflictIDENTITY_COLLISIONA member with this external_user_id or email already exists in this project.