Search
K
clearinghouse-usage

Clearinghouse Builder API

1.0.1OAS 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