Search
K
clearinghouse-usage

Clearinghouse Builder API

1.0.0OAS 3.1

Machine-facing Builder API for clearinghouse integrators. Provisions Auth0 end-users, OpenMeter customers, and mints short-lived signer JWTs.

API Base URL
  • Server 1:https://builder-api-production-82bf.up.railway.app

    Railway builder-api (Auth0 JWT or sk_*; default until Kong Gateway is linked)

  • Server 2:http://localhost:8095

    Local builder-api

  • Server 3:${KONNECT_PROXY_URL}

    Kong Gateway proxy (Auth0 JWT / DCR Bearer only; sk_* not accepted at the edge)

Security
m2mBasic (http)

M2M client id and secret (users:write, RFC 8693 token exchange)

tenantBasic (http)

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 (http)

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.

Health check

get

Response

200

OK

get/health
 
200

Create or upsert an end-user

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

post

Path Parameters

clientIdstringrequired

Public Auth0 client id for the integrator app

Body

application/json

CreateUserRequest

externalUserIdstringrequired
emailstring(email)
connectionstring
issueApiKeyboolean

Default:true

Response

application/json

User updated

CreateUserResponse

idstring
clientIdstring
externalUserIdstring
emailstring
statusstring
apiKeystring

Returned once when issueApiKey is true

post/api/v1/apps/{clientId}/users

Body

{ "externalUserId": "externalUserId" }
 
application/json

RFC 8693 signer session token exchange

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.

post

Path Parameters

clientIdstringrequired

Public Auth0 client id for the integrator app

Body

application/x-www-form-urlencoded

TokenExchangeRequest

grant_typestringrequired

Allowed values:urn:ietf:params:oauth:grant-type:token-exchange

subject_tokenstringrequired

Auth0 user access token (JWT) or end-user API key (sk_*)

subject_token_typestringrequired

Allowed values:urn:ietf:params:oauth:token-type:access_token

requested_token_typestring

Allowed values:urn:ietf:params:oauth:token-type:access_token

audiencestring

Must match configured signer audience when provided

resourcestring

Must match configured signer audience when provided

Response

application/json

Signer session

SignerSession

access_tokenstringrequired
token_typestringrequired

Allowed values:Bearer

expires_inintegerrequired
scopestringrequired
signer_urlstring(uri)
discovery_urlstring(uri)
issued_token_typestring
correlation_idstring
has_accessbooleanrequired

Whether the customer currently has allowance. Always present.

balance_usd_microsinteger(int64)required

Allowance balance in USD micros. Always present.

post/api/v1/apps/{clientId}/oidc/token

Body

{ "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "subject_token": "subject_token", "subject_token_type": "urn:ietf:params:oauth:token-type:access_token" }
 
application/json

Query own metered usage for an app

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.

get

Query Parameters

meterstringrequired

Allowed values:network_fee_usd_microsbillable_usd_microssigned_ticket_countfee_weibillable_secsnetwork_fee_usd_micros_by_manifest

externalUserIdstring

Optional. When set must equal the authenticated actor.

fromstring(date-time)
tostring(date-time)
groupByarray[string]

Extra catalog dimensions. client_id and external_user_id are always included server-side.

Path Parameters

clientIdstringrequired

Response

Actor-scoped usage rows

get/api/v1/apps/{clientId}/usage