---
title: "Clearinghouse Builder API"
url: "https://livepeer.pymthouse.com/apis/clearinghouse-usage/versions/295ecb35-5fcc-474e-a596-7431f5a1e8aa"
---

# Clearinghouse Builder API

OpenAPI specification document.

```json
{"openapi":"3.1.0","info":{"title":"Clearinghouse Builder API","version":"1.0.1","description":"Machine-facing Builder API for clearinghouse integrators. Provisions Auth0 end-users, OpenMeter customers, and mints short-lived signer JWTs."},"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":{"/health":{"get":{"summary":"Health check","responses":{"200":{"description":"OK"}}}},"/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"}}}},"/api/v1/apps/{clientId}/oidc/token":{"post":{"summary":"RFC 8693 signer session token exchange","description":"Exchanges an Auth0 end-user access token (device code / authorization code) or end-user API key (`sk_*`) for a short-lived signer JWT. The `{clientId}` path segment is the public Auth0 app client id. Authenticate with the end-user `subject_token`; optional HTTP Basic with the signer M2M client is supported for server-side callers.","parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"},"description":"Public Auth0 client id for the integrator app"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenExchangeRequest"}}}},"responses":{"200":{"description":"Signer session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignerSession"}}}},"400":{"description":"Invalid request, grant, target, or unsupported token type"},"401":{"description":"Invalid client credentials"}}}},"/api/v1/apps/{clientId}/usage":{"get":{"summary":"Query own metered usage for an app","description":"Returns OpenMeter rows for the authenticated actor only. Authenticate with Bearer Auth0 user JWT (via Kong Gateway or Railway) or sk_* API key (Railway direct only). Path clientId must match the credential app. Optional externalUserId must equal the actor when set. Meters and groupBy dimensions are constrained to the provisioned catalog.","security":[{"userBearer":[]}],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},{"name":"meter","in":"query","required":true,"schema":{"type":"string","enum":["network_fee_usd_micros","billable_usd_micros","signed_ticket_count","fee_wei","billable_secs","network_fee_usd_micros_by_manifest"]}},{"name":"externalUserId","in":"query","description":"Optional. When set must equal the authenticated actor.","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"groupBy","in":"query","description":"Extra catalog dimensions. client_id and external_user_id are always included server-side.","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Actor-scoped usage rows"},"400":{"description":"Invalid meter, groupBy, time window, or externalUserId"},"401":{"description":"Missing or invalid Bearer credentials (including M2M Basic)"},"404":{"description":"Path clientId does not match the credential app"},"502":{"description":"Metering backend unavailable"},"503":{"description":"Metering backend not configured"}}}}},"components":{"securitySchemes":{"m2mBasic":{"type":"http","scheme":"basic","description":"M2M client id and secret (users:write, RFC 8693 token exchange)"},"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."},"userBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT or sk_*","description":"Auth0 end-user access token (JWT) or end-user API key (sk_*). Gateway ($KONNECT_PROXY_URL) accepts Auth0 JWT / DCR Bearer only; sk_* works on Railway direct. Path clientId must match the credential's app client id."}},"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"}}},"TokenExchangeRequest":{"type":"object","required":["grant_type","subject_token","subject_token_type"],"properties":{"grant_type":{"type":"string","enum":["urn:ietf:params:oauth:grant-type:token-exchange"]},"subject_token":{"type":"string","description":"Auth0 user access token (JWT) or end-user API key (sk_*)"},"subject_token_type":{"type":"string","enum":["urn:ietf:params:oauth:token-type:access_token"]},"requested_token_type":{"type":"string","enum":["urn:ietf:params:oauth:token-type:access_token"]},"audience":{"type":"string","description":"Must match configured signer audience when provided"},"resource":{"type":"string","description":"Must match configured signer audience when provided"}}},"SignerSession":{"type":"object","required":["access_token","token_type","expires_in","scope","has_access","balance_usd_micros"],"properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer"},"scope":{"type":"string"},"signer_url":{"type":"string","format":"uri"},"discovery_url":{"type":"string","format":"uri"},"issued_token_type":{"type":"string"},"correlation_id":{"type":"string"},"has_access":{"type":"boolean","description":"Whether the customer currently has allowance. Always present."},"balance_usd_micros":{"type":"integer","format":"int64","description":"Allowance balance in USD micros. Always present."}}}}}}
```