Skip to content
autom8y

Resolve Identifiers

POST
/internal/identifiers/resolve

Resolve batch of identifiers between Auth UUIDs and external IDs.

This endpoint provides centralized identifier resolution for services that need to map between Auth service UUIDs and external identifiers (e.g., NHC guid values from MySQL).

Supports bidirectional lookup per FR-IDENTIFIER-002:

  • auth_uuid -> external_id
  • external_business_id -> auth_uuid
  • external_user_id -> auth_uuid

Batch limit: 100 identifiers (FR-IDENTIFIER-005) Returns partial results for mixed valid/invalid identifiers (FR-IDENTIFIER-006) Supports numeric guid resolution via guid_migrations table (FR-IDENTIFIER-007)

Args: request: Resolution request with identifiers, id_type, and entity_type x_api_key: Service API key from X-API-Key header db: Database session from dependency injection

Returns: IdentifierResolveResponse with resolved mappings and not_found list

Raises: 400: If batch too large or invalid id_type/entity_type combination 401: If API key is invalid or revoked 403: If API key is not a service account

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
X-API-Key
required
X-Api-Key
string

Request Body required

Section titled “Request Body required ”
IdentifierResolveRequest

Request schema for batch identifier resolution (FR-IDENTIFIER-001, FR-IDENTIFIER-005).

Attributes: identifiers: List of identifiers to resolve (max 100) id_type: Type of identifier being provided entity_type: Entity type to search (user or business)

object
identifiers
required
Identifiers

List of identifiers to resolve (max 100)

Array<string>
>= 1 items <= 100 items
id_type
required
Id Type

Type of identifier being provided

string
Allowed values: auth_uuid external_business_id external_user_id
entity_type
required
Entity Type

Entity type to search

string
Allowed values: user business

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

IdentifierResolveResponse

Response schema for batch identifier resolution (FR-IDENTIFIER-006).

Attributes: resolved: Successfully resolved identifiers not_found: Identifiers that could not be resolved

object
resolved
Resolved

Successfully resolved identifiers

Array<object>
ResolvedIdentifier

Single resolved identifier mapping (FR-IDENTIFIER-003).

Attributes: input: Original input identifier auth_uuid: Auth service UUID external_id: External identifier (NHC guid) if available entity_type: Entity type (user or business)

object
input
required
Input

Original input identifier

string
auth_uuid
required
Auth Uuid

Auth service UUID

string
external_id
Any of:
string
entity_type
required
Entity Type
string
Allowed values: user business
not_found
Not Found

Identifiers that could not be resolved

Array<string>

400

Section titled “400 ”

Invalid request (batch too large or invalid parameters)

Examples
{
  "detail": {
    "error": "batch_too_large",
    "message": "Maximum 100 identifiers per request",
    "max": 100
  }
}

401

Section titled “401 ”

Invalid API key

Example
{
  "detail": {
    "error": "invalid_api_key"
  }
}

403

Section titled “403 ”

API key is not a service account

Example
{
  "detail": {
    "error": "not_service_account"
  }
}

422

Section titled “422 ”

Validation Error

HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object

429

Section titled “429 ”

Rate limited

Example
{
  "detail": {
    "error": "rate_limited",
    "retry_after": 60
  }
}