Identity tracking for user analytics

Associate requests with Identity identifiers for user-level observability and analytics.

Identities are Orq.ai entities used to track project expenses and token usage per user or team.

Why use identity tracking

Per-user cost attribution and cross-charging to tenants or customers.
Enforcing per-user rate limits to prevent abuse.
Identifying which users generate the most load or cost.
Linking LLM usage to existing user analytics for cohort analysis.

Use Cases

Scenario	Identity ID Strategy	Metadata Example
User Analytics	`user-{userId}`	`[{"plan": "pro", "usage_tier": "high"}]`
Customer Support	`support-{ticketId}`	`[{"priority": "high", "issue_type": "billing"}]`
A/B Testing	`test-{userId}-{variant}`	`[{"experiment": "pricing-v2", "variant": "b"}]`
Multi-tenant	`tenant-{orgId}-{userId}`	`[{"org": "acme-corp", "role": "admin"}]`

Quick Start

Pass a stable identifier from the system (a database user ID, UUID, or similar string) as identity.id on any request.

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "How can I upgrade my account?",
    "identity": {
      "id": "user_123",
      "display_name": "John Smith",
      "email": "john@example.com",
      "metadata": [{"plan": "premium", "signup_date": "2024-01-15"}]
    }
  }'

Identity resolution

The gateway checks each of the following sources in order and uses the first match found:

Order	Source	Effect
1	`identity` object in the request body	Tags the request and upserts the identity record (name, email, metadata)
2	`X-ORQ-IDENTITY-ID` request header	Tags the request only; does not update the identity record
3	API key owner	Tags the request only; applies automatically when the key is user-owned

Body
X-ORQ-IDENTITY-ID Header
API Key Owner

Pass the identity object in the request body to attribute the request and keep the identity record up to date. See the Quick Start above for full examples.

curl -X POST https://api.orq.ai/v3/router/chat/completions \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "identity": {
      "id": "user_123",
      "display_name": "John Smith",
      "email": "john@example.com"
    }
  }'

Use the X-ORQ-IDENTITY-ID header to tag a request without modifying the body. Useful in middleware or proxy layers where the payload is opaque.

The X-ORQ-IDENTITY-ID header does not upsert the identity record. Use the body identity object to keep the identity’s display name, email, and metadata up to date.

The identity must already exist before using this header. If no identity with the given ID has been created via the body method or the Create identity endpoint, the request is processed but the tag is not attributed to any identity record.

curl -X POST https://api.orq.ai/v3/router/chat/completions \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "X-ORQ-IDENTITY-ID: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

When a request includes no identity body field and no X-ORQ-IDENTITY-ID header, the request is automatically attributed to the API key’s owner, provided the key is user-owned. No additional configuration is required.

Configuration

Parameter	Type	Required	Description	Constraints
`id`	string	Yes	Unique identity identifier	Max 255 characters
`display_name`	string	No	Human-readable identity name
`email`	string	No	Identity email address
`metadata`	object[]	No	Array of objects with custom key-value pairs	Max 20 fields
`logo_url`	string	No	URL to identity’s profile image
`tags`	string[]	No	Classification tags for identity segmentation	Max 10 tags

Identities: manage, list, and view metrics

Covers creating identities via the dashboard or API, listing with 30-day usage metrics, and retrieving identity records.

​Why use identity tracking

​Use Cases

​Quick Start

​Identity resolution

​Configuration

Identities: manage, list, and view metrics

Why use identity tracking

Use Cases

Quick Start

Identity resolution

Configuration