---
title: "Resolve Principal"
method: POST
path: "/api/principals/resolve"
tags: ["principals"]
---

# Resolve Principal

`POST /api/principals/resolve`

## Request

- Base URL: `https://www.gateco.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://www.gateco.ai/api/principals/resolve`
- Auth: OAuth 2 (password, token URL `/api/auth/login`)

Resolve a principal by email or provider_subject without creating one.

Lookup order:
1. If ``email`` is provided, match on ``(org_id, email, status=active)``
   ordered by ``last_seen DESC NULLS LAST``.
2. If no email match (or ``email`` was not provided), and ``provider_subject``
   is provided, match on ``(org_id, provider_subject, status=active)``
   optionally scoped by ``identity_provider_id``.

Returns 404 with an actionable message when no active principal is found.

## Request body

- ResolveRequest: Request body for the principal resolver endpoint. At least one of ``email`` or ``provider_subject`` must be supplied. When both are provided the resolver queries by email first and falls back to ``provider_subject`` only if no email match is found. Optionally scope the ``provider_subject`` lookup to a specific IDP via ``identity_provider_id``.
  - `email` string, nullable
  - `provider_subject` string, nullable
  - `identity_provider_id` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/gateco/apis/gateco-api.md) · [All operations](https://skmtc.dev/gateco/apis/gateco-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gateco/apis/gateco-api/revisions/5debaf204950?raw)