API Reference

Principals API

Manage all identity principals in TigerIdentity. Create and query users, service accounts, API keys, and AI agents. Access the unified identity graph and track access relationships.

Get StartedIdentity Fabric
Base URL: https://api.tigeridentity.com/v1

Principal Types

USER

Human users authenticated via IdP

SERVICE_ACCOUNT

Non-human service identities

API_KEY

API key-based authentication

AI_AGENT

AI agents with tool access

Endpoints

GET/principalsList all principals
POST/principalsCreate new principal
GET/principals/{id}Get principal by ID
PATCH/principals/{id}Update principal
DELETE/principals/{id}Delete principal
POST/principals/searchSearch principals
GET/principals/{id}/accessGet principal access
GET/principals/{id}/relationshipsGet identity graph
GET/principals

List all principals with filtering and pagination

Query Parameters

pagenumber

Page number (default: 1)

limitnumber

Results per page (default: 50, max: 100)

typestring

Filter by type (USER, SERVICE_ACCOUNT, API_KEY, AI_AGENT)

connectorstring

Filter by connector source

cURL Example

curl -X GET \
  "https://api.tigeridentity.com/v1/principals?type=USER&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "data": [
    {
      "id": "principal_abc123",
      "type": "USER",
      "email": "[email protected]",
      "name": "Alice Smith",
      "attributes": {
        "department": "engineering",
        "role": "senior-engineer",
        "manager_id": "principal_xyz789"
      },
      "connector_source": "okta",
      "status": "active",
      "created_at": "2026-01-10T08:00:00Z",
      "last_login": "2026-02-05T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 234,
    "page": 1,
    "per_page": 20,
    "pages": 12
  }
}

Create Principal

POST/principals

Create a new principal (service account or AI agent)

Request Body (Service Account)

{
  "type": "SERVICE_ACCOUNT",
  "name": "Production Backend Service",
  "description": "Main backend service for prod",
  "attributes": {
    "environment": "production",
    "team": "backend",
    "service_type": "api"
  },
  "metadata": {
    "owner": "[email protected]",
    "repository": "github.com/org/backend"
  }
}

Request Body (AI Agent)

{
  "type": "AI_AGENT",
  "name": "Customer Support AI",
  "description": "AI agent for customer inquiries",
  "attributes": {
    "model": "claude-opus-4",
    "capabilities": ["chat", "search", "ticket_creation"],
    "allowed_tools": ["zendesk", "slack"]
  },
  "metadata": {
    "owner": "[email protected]"
  }
}

Response

{
  "id": "principal_def456",
  "type": "SERVICE_ACCOUNT",
  "name": "Production Backend Service",
  "description": "Main backend service for prod",
  "attributes": {
    "environment": "production",
    "team": "backend",
    "service_type": "api"
  },
  "metadata": {
    "owner": "[email protected]",
    "repository": "github.com/org/backend"
  },
  "status": "active",
  "created_at": "2026-02-05T10:30:00Z",
  "created_by": "user_abc123"
}

Note: USER principals are typically created via connector sync from identity providers like Okta or Azure AD.

GET/principals/{id}

Retrieve detailed information about a principal

cURL Example

curl -X GET \
  "https://api.tigeridentity.com/v1/principals/principal_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "id": "principal_abc123",
  "type": "USER",
  "email": "[email protected]",
  "name": "Alice Smith",
  "attributes": {
    "department": "engineering",
    "role": "senior-engineer",
    "manager_id": "principal_xyz789",
    "location": "US-CA-SF"
  },
  "connector_source": "okta",
  "connector_id": "00u1a2b3c4d5e6f7g8",
  "status": "active",
  "created_at": "2026-01-10T08:00:00Z",
  "updated_at": "2026-02-05T09:15:00Z",
  "last_login": "2026-02-05T09:15:00Z",
  "risk_score": 25
}
PATCH/principals/{id}

Update principal attributes or metadata

Request Body

{
  "attributes": {
    "role": "lead-engineer",
    "team": "platform"
  },
  "metadata": {
    "cost_center": "ENG-001"
  }
}

Response

{
  "id": "principal_abc123",
  "type": "USER",
  "email": "[email protected]",
  "attributes": {
    "department": "engineering",
    "role": "lead-engineer",
    "team": "platform"
  },
  "metadata": {
    "cost_center": "ENG-001"
  },
  "updated_at": "2026-02-05T14:30:00Z"
}

Search Principals

POST/principals/search

Advanced search with complex filters on attributes and metadata

Request Body

{
  "query": {
    "type": ["USER", "SERVICE_ACCOUNT"],
    "attributes": {
      "department": "engineering",
      "role": {
        "$in": ["senior-engineer", "lead-engineer"]
      }
    },
    "status": "active"
  },
  "sort": {
    "field": "created_at",
    "order": "desc"
  },
  "page": 1,
  "limit": 50
}

Search Operators

$in

Value in array

$gt, $lt, $gte, $lte

Comparison operators

$contains

String contains

Response

{
  "data": [
    {
      "id": "principal_abc123",
      "type": "USER",
      "email": "[email protected]",
      "name": "Alice Smith",
      "attributes": {
        "department": "engineering",
        "role": "senior-engineer"
      },
      "status": "active"
    },
    {
      "id": "principal_def456",
      "type": "SERVICE_ACCOUNT",
      "name": "Prod Backend",
      "attributes": {
        "department": "engineering",
        "environment": "production"
      },
      "status": "active"
    }
  ],
  "pagination": {
    "total": 28,
    "page": 1,
    "per_page": 50,
    "pages": 1
  }
}
GET/principals/{id}/access

Get all resources and permissions the principal has access to

cURL Example

curl -X GET \
  "https://api.tigeridentity.com/v1/principals/principal_abc123/access" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "principal_id": "principal_abc123",
  "access": [
    {
      "resource": {
        "type": "database",
        "identifier": "prod-db-main"
      },
      "actions": ["read", "write"],
      "granted_by": ["policy_xyz789"],
      "granted_at": "2026-02-05T09:15:00Z"
    },
    {
      "resource": {
        "type": "api",
        "identifier": "internal-api"
      },
      "actions": ["read"],
      "granted_by": ["policy_abc123"],
      "granted_at": "2026-02-04T10:00:00Z"
    }
  ],
  "total_resources": 12
}

Identity Graph Relationships

GET/principals/{id}/relationships

Query the identity graph to find related principals and connections

Query Parameters

typestring

Relationship type (manager, reports, group_member)

depthnumber

Graph traversal depth (default: 1, max: 3)

cURL Example

curl -X GET \
  "https://api.tigeridentity.com/v1/principals/principal_abc123/relationships?type=reports&depth=2" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "principal_id": "principal_abc123",
  "relationships": [
    {
      "type": "manager",
      "principal": {
        "id": "principal_xyz789",
        "name": "Bob Johnson",
        "type": "USER",
        "email": "[email protected]"
      },
      "depth": 1
    },
    {
      "type": "reports",
      "principals": [
        {
          "id": "principal_def456",
          "name": "Carol White",
          "type": "USER",
          "email": "[email protected]"
        }
      ],
      "depth": 1,
      "count": 1
    }
  ]
}
DELETE/principals/{id}

Delete a principal (service accounts and AI agents only)

cURL Example

curl -X DELETE \
  "https://api.tigeridentity.com/v1/principals/principal_def456" \
  -H "Authorization: Bearer YOUR_TOKEN"

Note: USER principals cannot be deleted via API. They are managed by connector sync.

Response

{
  "id": "principal_def456",
  "status": "deleted",
  "deleted_at": "2026-02-05T16:00:00Z",
  "deleted_by": "user_abc123"
}

Related Documentation

Identity Fabric

Learn about the unified identity graph and entity resolution.

Learn more

Policies API

Define access policies that govern principal permissions.

Learn more

Connectors

Sync principals from identity providers and cloud platforms.

Learn more

Ready to manage principals?

Start building your unified identity fabric with the Principals API.

Get StartedIdentity Fabric