Owners Endpoints

The Owners API provides endpoints for managing identity owners, their accounts, and organizational relationships.

Base URL

All endpoints are relative to /api/v1/owners.

---

List Owners

Retrieve a paginated list of owners.

GET /api/v1/owners

Query Parameters

Parameter	Type	Description
search	string	Search by name or email
department	string	Filter by department
status	string	Filter by status (active, inactive)
owner_type	string	Filter by type (human, service, federated)
first	number	Number of items to return
after	string	Cursor for pagination

Response

{
  "owners": [
    {
      "id": "own-123",
      "name": "John Doe",
      "email": "john.doe@company.com",
      "department": "Engineering",
      "title": "Senior Developer",
      "owner_type": "human",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "cursor-token"
  }
}

---

Get Owner

Retrieve details for a specific owner.

GET /api/v1/owners/{id}

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Response

Returns the complete owner object with all fields.

---

Create Owner

Create a new owner record.

POST /api/v1/owners

::: note Administrator Only This endpoint requires Administrator role. :::

Request Body

{
  "name": "Jane Smith",
  "email": "jane.smith@company.com",
  "department": "Finance",
  "title": "Financial Analyst",
  "owner_type": "human"
}

Response

Returns the created owner object.

---

Update Owner

Update an existing owner.

PUT /api/v1/owners/{id}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Request Body

Include only the fields to update.

Response

Returns the updated owner object.

---

Delete Owner

Delete an owner record.

DELETE /api/v1/owners/{id}

::: note Administrator Only This endpoint requires Administrator role. :::

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Response

Returns 204 No Content on success.

---

Sync Owners

Trigger owner synchronization from data sources.

POST /api/v1/owners/sync

::: note Administrator Only This endpoint requires Administrator role. :::

Response

{
  "status": "queued",
  "message": "Owner sync initiated"
}

---

Get Owner Accounts

Retrieve accounts owned by a specific owner.

GET /api/v1/owners/{id}/accounts

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Response

{
  "accounts": [
    {
      "id": "acc-123",
      "name": "john.doe",
      "email": "john.doe@company.com",
      "application": "Salesforce",
      "status": "active"
    }
  ],
  "count": 5
}

---

Batch Get Owner Accounts

Retrieve accounts for multiple owners in a single request.

POST /api/v1/owners/accounts

Request Body

{
  "owner_ids": ["own-123", "own-456"]
}

Response

{
  "own-123": [...accounts],
  "own-456": [...accounts]
}

---

Get Owner Manager

Retrieve the manager of an owner.

GET /api/v1/owners/{id}/manager

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Response

Returns the manager owner object, or null if no manager is assigned.

---

Get Direct Reports

Retrieve direct reports of an owner.

GET /api/v1/owners/{id}/direct-reports

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Response

{
  "direct_reports": [
    {
      "id": "own-456",
      "name": "Jane Smith",
      "email": "jane.smith@company.com",
      "title": "Developer"
    }
  ],
  "count": 3
}

---

Get Owner Roles

Retrieve roles assigned to an owner.

GET /api/v1/owners/{id}/roles

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Response

{
  "roles": [
    {
      "id": "role-123",
      "name": "Engineering - Senior",
      "department": "Engineering",
      "title": "Senior Developer"
    }
  ]
}

---

Get Owner Audit Trail

Retrieve audit trail for an owner.

GET /api/v1/owners/{id}/audit-trail

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Query Parameters

Parameter	Type	Description
limit	number	Number of entries to return

Response

{
  "entries": [
    {
      "timestamp": "2024-02-01T10:00:00Z",
      "action": "account_added",
      "details": "Account acc-789 linked to owner"
    }
  ]
}

---

Owner Statistics and Risk Metrics

Get Owner Statistics

Retrieve calculated statistics and risk metrics for an owner.

GET /api/v1/owners/{id}/statistics

Path Parameters

Parameter	Type	Description
id	string	Owner ID

Response

{
  "identity_info": {
    "identity_id": "user-123",
    "identity_name": "John Doe",
    "identity_email": "john.doe@company.com",
    "alt_email": "jdoe@personal.com",
    "department": "Engineering",
    "title": "Senior Developer",
    "location": "New York",
    "manager": "Jane Manager",
    "owner_type": "Employee",
    "status": "Active"
  },
  "contact_info": {
    "mobile_phone": "+1-555-0123",
    "phone": "+1-555-0199"
  },
  "employment_info": {
    "start_date": "2020-01-15",
    "end_date": null
  },
  "account_statistics": {
    "total_accounts": 12,
    "active_accounts": 10,
    "disabled_accounts": 2,
    "child_count": 12
  },
  "risk_metrics": {
    "total_threat": "45",
    "breached_accounts": "0",
    "accounts_without_mfa": "3",
    "privileged_accounts_not_vaulted": "1",
    "shared_accounts": "0",
    "inactive_owners_enabled_accounts": "0"
  },
  "activity_metrics": {
    "not_used_90": "2",
    "not_used_180": "1",
    "not_used_365": "0",
    "failed_logins_in_hour": "0"
  },
  "password_security": {
    "accounts_with_password_never": "0",
    "accounts_with_password_90": "1",
    "accounts_with_password_180": "2",
    "accounts_with_password_365": "0"
  },
  "privilege_metrics": {
    "all_privileged_groups": "2",
    "highly_privileged_groups": "0",
    "highly_privileged_roles": "0"
  },
  "compliance_metrics": {
    "accounts_no_owner": "0",
    "mapped_accounts": "12",
    "account_group_deviation": "0"
  }
}

Get Owner Risk Assessment

Get detailed risk assessment for an owner showing risk factors across all their accounts.

GET /api/v1/owners/{id}/risk-assessment

Response

{
  "overall_risk_score": 45,
  "risk_level": "medium",
  "risk_factors": [
    {
      "category": "MFA Gaps",
      "affected_accounts": 3,
      "severity": "medium",
      "description": "Accounts without multi-factor authentication"
    },
    {
      "category": "Stale Accounts",
      "affected_accounts": 2,
      "severity": "low",
      "description": "Accounts not used in 90+ days"
    }
  ],
  "recommendations": [
    "Enable MFA on all accounts",
    "Review and disable unused accounts"
  ]
}

Search Owners by Metadata

Perform advanced searches using dynamic field queries.

POST /api/v1/owners/search

Request Body

{
  "search_terms": ["engineering", "senior"],
  "search_operator": "AND",
  "search_fields": ["department", "title"],
  "field_queries": [
    {
      "field": "status",
      "operator": "equals",
      "value": "Active"
    },
    {
      "field": "total_threat",
      "operator": "greater_than",
      "value": 50
    }
  ],
  "limit": 50,
  "after": "cursor-token"
}

Response

Returns paginated list of owners matching the search criteria.

---

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
404	Not Found - Owner does not exist
500	Internal Server Error

---

Related Topics

• Accounts API - Account management endpoints
• Roles API - Role management endpoints
• API Reference - Complete API index