> ## Documentation Index > Fetch the complete documentation index at: https://docs.usechar.com/llms.txt > Use this file to discover all available pages before exploring further. # Create end user > Create a new end user for the current organization. The external_id should be your application's user identifier. End users are typically created automatically when widgets initialize, but you can pre-create them if needed. ## OpenAPI ````yaml https://app.usechar.ai/api/spec.json post /end-users openapi: 3.1.1 info: title: Char API version: 1.0.0 description: >- REST API for managing organizations, identity providers, end users, skills, threads, usage, and subscriptions. ## Authentication This API uses Bearer token authentication with WorkOS JWT tokens. Include the token in the Authorization header: ``` Authorization: Bearer ``` ## Authorization Levels - **Public endpoints**: No authentication required - **Protected endpoints**: Require valid JWT token (user authentication) - **Organization endpoints**: Require valid JWT token with organization context selected Most endpoints require organization context. Ensure your JWT token includes the `org_id` claim. ## Data Formats ### Allowed Domains The `allowed_domains` field is an array of origins (e.g., `https://app.example.com`). It is stored as JSON internally but surfaced as an array in the API. ### Timestamps All timestamps are returned as ISO 8601 strings (e.g., `"2025-01-15T10:30:00.000Z"`). ## Rate Limits No application-level rate limiting is currently enforced. ## Error Responses All errors follow a consistent format: ```json { "code": "ERROR_CODE", "status": 400, "message": "Human-readable error message", "data": { /* optional additional details */ } } ``` ### Error Codes | data.code | Description | |-----------|-------------| | `VALIDATION_ERROR` | Invalid input data (400) | | `AUTH_REQUIRED` | Missing or invalid authentication (401) | | `ACCESS_DENIED` | Permission denied (403) | | `PAYMENT_REQUIRED` | Subscription required (403) | | `ORG_CONTEXT_REQUIRED` | Organization selection required (403) | | `RESOURCE_NOT_FOUND` | Resource missing (404) | | `DUPLICATE_RESOURCE` | Resource already exists (409) | | `INTERNAL_ERROR` | Server-side error (500) | servers: - url: https://app.usechar.ai/api description: Production API security: - bearerAuth: [] tags: - name: Auth description: >- Authentication operations including session management and logout. All auth endpoints require a valid JWT token. - name: Users description: >- Access the current authenticated user's profile and organization memberships. - name: Organizations description: Organization details, members, and configuration such as allowed domains. - name: Identity Providers description: Manage SSO configuration and test IDP connectivity. - name: Directories description: Directory sync resources backed by WorkOS directories. - name: End Users description: End users who interact with embedded widgets, identified by IDP tokens. - name: Organization Skills description: CRUD for SKILL.md content following the Agent Skills spec. - name: Threads description: Conversation thread metadata and management. - name: Usage Analytics description: Usage and token analytics for the organization. - name: Plan Tiers description: Plan tiers and limit definitions. - name: Subscriptions description: Billing and subscription status via Polar integration. - name: OAuth description: OAuth 2.0 authorization flow endpoints for MCP client authentication. - name: OAuth Discovery description: RFC 8414/8707 well-known discovery endpoints for OAuth 2.0. paths: /end-users: post: tags: - End Users summary: Create end user description: >- Create a new end user for the current organization. The external_id should be your application's user identifier. End users are typically created automatically when widgets initialize, but you can pre-create them if needed. operationId: endUsers_create requestBody: required: true content: application/json: schema: type: object properties: organization_id: type: string description: WorkOS organization ID that owns the end user. external_id: type: string description: >- External user identifier from the embedding site or IDP token. email: anyOf: - type: string description: >- Optional email address provided by the identity provider. - type: 'null' metadata: anyOf: - type: string description: JSON string with additional end user metadata. - type: 'null' last_activity_at: anyOf: - type: string format: date-time x-native-type: date description: Timestamp of the user's last activity (message sent). - type: 'null' required: - organization_id - external_id description: >- Input for creating a new end user. Requires external_id (your system's user identifier). Email and metadata are optional. responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string description: Internal end user ID (UUID). organization_id: type: string description: WorkOS organization ID that owns the end user. external_id: type: string description: >- External user identifier from the embedding site or IDP token. email: anyOf: - type: string description: >- Optional email address provided by the identity provider. - type: 'null' metadata: anyOf: - type: string description: JSON string with additional end user metadata. - type: 'null' last_activity_at: anyOf: - type: string format: date-time x-native-type: date description: Timestamp of the user's last activity (message sent). - type: 'null' created_at: type: string format: date-time x-native-type: date description: Timestamp when the end user was created. updated_at: type: string format: date-time x-native-type: date description: Timestamp when the end user was last updated. required: - id - organization_id - external_id - email - metadata - last_activity_at - created_at - updated_at description: >- End user resource representing a user who interacts with embedded AI widgets. Identified by external_id from the embedding site. '400': description: '400' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: BAD_REQUEST status: const: 400 message: type: string default: Invalid request data data: type: object properties: code: const: VALIDATION_ERROR field: type: string details: type: string required: - code examples: - code: VALIDATION_ERROR field: email details: Invalid email format required: - defined - code - status - message - data - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message '401': description: '401' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: UNAUTHORIZED status: const: 401 message: type: string default: Authentication required data: type: object properties: code: const: AUTH_REQUIRED required: - code examples: - code: AUTH_REQUIRED required: - defined - code - status - message - data - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message '403': description: '403' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: FORBIDDEN status: const: 403 message: type: string default: Access denied data: type: object properties: code: const: ACCESS_DENIED reason: type: string required: - code examples: - code: ACCESS_DENIED reason: Insufficient permissions required: - defined - code - status - message - data - type: object properties: defined: const: true code: const: ORG_CONTEXT_REQUIRED status: const: 403 message: type: string default: Organization context required data: type: object properties: code: const: ORG_CONTEXT_REQUIRED required: - code examples: - code: ORG_CONTEXT_REQUIRED required: - defined - code - status - message - data - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message '404': description: '404' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: NOT_FOUND status: const: 404 message: type: string default: Resource not found data: type: object properties: code: const: RESOURCE_NOT_FOUND resource: type: string resourceId: type: string required: - code examples: - code: RESOURCE_NOT_FOUND resource: site resourceId: site_123 required: - defined - code - status - message - data - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message '409': description: '409' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: CONFLICT status: const: 409 message: type: string default: Resource already exists data: type: object properties: code: const: DUPLICATE_RESOURCE resource: type: string required: - code examples: - code: DUPLICATE_RESOURCE resource: api_key required: - defined - code - status - message - data - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message '500': description: '500' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: INTERNAL_SERVER_ERROR status: const: 500 message: type: string default: An internal error occurred data: type: object properties: code: const: INTERNAL_ERROR required: - code examples: - code: INTERNAL_ERROR required: - defined - code - status - message - data - type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- WorkOS JWT token. Obtain via WorkOS AuthKit authentication flow. The token must include organization_id claim for organization-scoped endpoints. ````