PERTIMEUSE PLATFORM API

One login and wallet for your application.

Use PerTimeUse as an identity provider, retrieve the authorized customer profile, and bill completed AI usage against their shared wallet. Connecting an API client does not automatically publish your service in the marketplace.

STEP 1

Create a platform client

Open the developer console, enter your application name and exact callback URL, then save the client ID and one-time client secret.

STEP 2

Authorize a customer

Use Authorization Code with PKCE. Generate a random verifier, its SHA-256 challenge and state value, then redirect the browser.

GET /oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://your-app.com/auth/callback&state=RANDOM_STATE&code_challenge=BASE64URL_SHA256_VERIFIER&code_challenge_method=S256

Exchange the returned code from your backend. Never expose the client secret in browser JavaScript.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=RETURNED_CODE&redirect_uri=YOUR_EXACT_CALLBACK&code_verifier=ORIGINAL_VERIFIER

CUSTOMER DATA

Profile and wallet

Send the access token using Authorization: Bearer ACCESS_TOKEN. Monetary values are integer USD microdollars: $1.00 equals 1,000,000.

METERED BILLING

Reserve, settle or cancel

Reserve the maximum expected charge before starting provider work. Settle the actual completed amount, or cancel when work fails.

POST /api/usage/reservations
{"productID":"your-service-code","sessionID":"provider-session-123","unit":"second","maximumAmountMicros":710000,"idempotencyKey":"start-provider-session-123"}

RESPONSES

Errors

API errors return JSON with ok: false and a stable error code. Treat 401 as expired authorization, 402 as insufficient available wallet balance, 409 as a state conflict, and 429 as a rate limit.

PRODUCTION CHECKLIST

Security requirements

• Keep client secrets on your backend only.
• Use HTTPS callback URLs in production.
• Validate state before exchanging a code.
• Use a unique idempotency key for every billing operation.
• Settle only verified, completed provider usage.