> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an identity > Creates a new identity with a unique external_id. If an identity with the same external_id already exists, the operation will fail. ## OpenAPI ````yaml post /v2/identities openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - description: List models available through the AI Router. name: Models - name: Guardrail Rules - name: Policies - name: Routing Rules - name: API keys description: >- API keys authenticate programmatic access to the workspace. The unified key model exposes opaque tokens, per-domain access grants, and budget / rate-limit constraints (see ADR 0001 and ADR 0002). - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, api-key, provider, and model. A budget is hierarchical and defense-in-depth — every applicable budget is a hard gate, and the most restrictive one wins per dimension (see ADR 0007). - name: Documentation description: >- Search the orq.ai documentation. Proxies the workspace's query to the hosted docs search index. - name: Files description: File upload and retrieval operations. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Projects description: Projects organize resources within a workspace - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/identities: post: tags: - Identities summary: Create an identity description: >- Creates a new identity with a unique external_id. If an identity with the same external_id already exists, the operation will fail. operationId: CreateIdentity requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateIdentityRequest' required: true responses: '201': description: Identity created successfully. content: application/json: schema: $ref: '#/components/schemas/CreateIdentityResponse' x-code-samples: - lang: curl label: Core - Create customer identity source: | curl --request POST \ --url 'https://api.orq.ai/v2/identities' \ --header 'Authorization: Bearer $ORQ_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "external_id": "customer_12345", "display_name": "Ada Lovelace", "email": "ada@example.com", "tags": ["enterprise", "beta"], "metadata": { "plan": "enterprise", "region": "eu" } }' - lang: python label: Python - Create customer identity source: | import os from orq_ai_sdk import Orq client = Orq(api_key=os.environ["ORQ_API_KEY"]) result = client.identities.create( external_id="customer_12345", display_name="Ada Lovelace", email="ada@example.com", tags=["enterprise", "beta"], metadata={ "plan": "enterprise", "region": "eu", }, ) print(result.identity.external_id) - lang: typescript label: Node.js - Create customer identity source: | import { Orq } from '@orq-ai/node'; const client = new Orq({ apiKey: process.env.ORQ_API_KEY, }); const result = await client.identities.create({ externalId: 'customer_12345', displayName: 'Ada Lovelace', email: 'ada@example.com', tags: ['enterprise', 'beta'], metadata: { plan: 'enterprise', region: 'eu', }, }); console.log(result.identity.externalId); - lang: curl label: Core - Create minimal identity source: | curl --request POST \ --url 'https://api.orq.ai/v2/identities' \ --header 'Authorization: Bearer $ORQ_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "external_id": "user_9f4b2a" }' - lang: python label: Python - Create minimal identity source: | import os from orq_ai_sdk import Orq client = Orq(api_key=os.environ["ORQ_API_KEY"]) result = client.identities.create( external_id="user_9f4b2a", ) print(result.identity.external_id) - lang: typescript label: Node.js - Create minimal identity source: | import { Orq } from '@orq-ai/node'; const client = new Orq({ apiKey: process.env.ORQ_API_KEY, }); const result = await client.identities.create({ externalId: 'user_9f4b2a', }); console.log(result.identity.externalId); components: schemas: CreateIdentityRequest: required: - external_id type: object properties: external_id: type: string description: >- Customer-provided stable identifier for this identity. Must be unique within the workspace. display_name: type: string description: Human-readable display name for the identity. email: type: string description: Email address associated with the identity. avatar_url: type: string description: URL of the identity avatar image. tags: type: array items: type: string description: Free-form labels used to organize and filter identities. metadata: type: object description: Custom JSON metadata stored with the identity. CreateIdentityResponse: required: - identity type: object properties: identity: allOf: - $ref: '#/components/schemas/Identity' description: Newly created identity. Identity: required: - _id - external_id - workspace_id - created - updated type: object properties: _id: type: string description: |- Unique identity identifier assigned by ORQ. Returned as `_id` for compatibility with the v1 identity API. external_id: type: string description: |- Customer-provided stable identifier for this identity. This value is required on create and is unique within the workspace. workspace_id: type: string description: Workspace that owns the identity. display_name: type: string description: Human-readable display name for the identity. email: type: string description: Email address associated with the identity. avatar_url: type: string description: URL of the identity avatar image. tags: type: array items: type: string description: Free-form labels used to organize and filter identities. metadata: type: object description: Custom JSON metadata stored with the identity. created: type: string description: ISO timestamp for when the identity was created. updated: type: string description: ISO timestamp for when the identity was last updated. metrics: allOf: - $ref: '#/components/schemas/IdentityMetrics' description: |- Optional usage and cost metrics. Present only when requested with `include_metrics`. IdentityMetrics: required: - total_tokens - total_cost - total_requests - error_rate type: object properties: total_tokens: type: number description: Total token count attributed to the identity. format: double total_cost: type: number description: Total cost attributed to the identity. format: double total_requests: type: number description: Total request count attributed to the identity. format: double error_rate: type: number description: Fraction of attributed requests that failed. format: double securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````