OAuth2 token rejected when posting billing data via REST API in multi-tenant billing engine integration

scott_lead
Wed, 05 Feb 2025 21:53:22 +0000

Let me provide a complete solution addressing all the OAuth2 token requirements, multi-tenant configuration, and permission scopes for billing API access.

OAuth2 Token Claim Requirements: Your token must include these specific claims:

scope: ‘urn:oracle:iot:billing:write’ (full URN format required)

aud: Must include ‘https://iot.oraclecloud.com/billing’ in the audience array

tenant_id: Your organization’s tenant identifier

exp: Token expiration (note: billing tokens have 15-minute lifetime vs 60-minute for standard APIs)

Request token with proper scope:

POST /oauth2/v1/token
grant_type=client_credentials
scope=urn:oracle:iot:billing:write
client_id={your_client_id}
client_secret={your_client_secret}

Multi-Tenant API Header Configuration: Billing endpoints require these headers:

POST /iot/api/v2/billing/events
Authorization: Bearer {token_with_billing_scope}
X-Tenant-ID: {org_tenant_id}
X-Application-ID: {registered_app_id}
Content-Type: application/json

The X-Tenant-ID must match the tenant_id claim in your token. Get this from IoT Console > Settings > Organization Details. X-Application-ID is your OAuth client ID registered in Applications > OAuth Clients.

REST API Permission Scopes: Configure your OAuth client in IoT Cloud Platform console:

1. Navigate to Applications > OAuth Clients > Your Application

2. Add API Permissions: Select ‘Billing Services’ category

3. Enable these specific scopes:

urn:oracle:iot:billing:write (for POST operations)

urn:oracle:iot:billing:read (if you need to query billing data)

4. Save and regenerate client credentials

Critical Implementation Notes:

Billing API validates both token claims AND request headers - both must align

Token refresh is essential: Implement refresh logic at 12-minute intervals (before 15-min expiration)

Multi-tenant validation: The platform verifies tenant_id claim matches X-Tenant-ID header AND your client is authorized for that tenant

Rate limiting: Billing endpoints have stricter limits (100 req/min vs 500 for device APIs)

Verification Steps:

1. Decode your JWT at jwt.io - verify all required claims are present

2. Test with curl including all headers to isolate authentication from application code

3. Check audit logs in IoT Console > Monitoring > API Access for detailed rejection reasons

4. Ensure your OAuth client has ‘Billing API Access’ checkbox enabled in the console

The “insufficient claims” error specifically means either the scope claim is missing/wrong or the aud claim doesn’t include the billing service endpoint. Fix both in your token request, add the required headers, and your billing sync should work.