---
title: "Create or upsert an end-user"
url: "https://livepeer.pymthouse.com/apis/clearinghouse-usage/versions/295ecb35-5fcc-474e-a596-7431f5a1e8aa/paths/api-v1-apps-clientId--users/post"
---

> Full API specification: https://livepeer.pymthouse.com/apis/clearinghouse-usage/versions/295ecb35-5fcc-474e-a596-7431f5a1e8aa.md

# Create or upsert an end-user

`POST` `/api/v1/apps/{clientId}/users`

Creates an Auth0 Database user, upserts the OpenMeter customer, and optionally issues an end-user API key.

## Path parameters

- `clientId` (string, required) - Public Auth0 client id for the integrator app

## Request body (required)

Content types: `application/json`

## Responses

- `200` - User updated
- `201` - User created
- `400` - Bad request
- `401` - Unauthorized

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Clearinghouse Builder API
  version: 1.0.1
servers:
  - url: https://builder-api-production-82bf.up.railway.app
    description: Railway builder-api (Auth0 JWT or sk_*; default until Kong Gateway
      is linked)
  - url: http://localhost:8095
    description: Local builder-api
  - url: ${KONNECT_PROXY_URL}
    description: Kong Gateway proxy (Auth0 JWT / DCR Bearer only; sk_* not accepted
      at the edge)
paths:
  /api/v1/apps/{clientId}/users:
    post:
      summary: Create or upsert an end-user
      description: Creates an Auth0 Database user, upserts the OpenMeter customer, and
        optionally issues an end-user API key.
      security:
        - tenantBasic: []
        - m2mBasic: []
      parameters:
        - name: clientId
          in: path
          required: true
          schema:
            type: string
          description: Public Auth0 client id for the integrator app
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateUserResponse"
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateUserResponse"
        "400":
          description: Bad request
        "401":
          description: Unauthorized
security:
  - tenantBasic: []
  - m2mBasic: []
components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - externalUserId
      properties:
        externalUserId:
          type: string
        email:
          type: string
          format: email
        connection:
          type: string
        issueApiKey:
          type: boolean
          default: true
    CreateUserResponse:
      type: object
      properties:
        id:
          type: string
        clientId:
          type: string
        externalUserId:
          type: string
        email:
          type: string
        status:
          type: string
        apiKey:
          type: string
          description: Returned once when issueApiKey is true
  securitySchemes:
    tenantBasic:
      type: http
      scheme: basic
      description: "Tenant admin credentials: username is the tenant clientId,
        password is its secret from TENANT_ADMIN_KEYS. A tenant may only address
        its own clientId; the platform M2M credential (m2mBasic) may address
        any. A request for another tenant answers 404, not 403, so that a shared
        OpenMeter tenant does not confirm which client ids exist. Not accepted
        on the usage route."
    m2mBasic:
      type: http
      scheme: basic
      description: M2M client id and secret (users:write, RFC 8693 token exchange)
```