Platform API Reference

The Platform API enables partner platforms to integrate with Oncade and manage resources on behalf of businesses that have granted them access. Platforms can create campaigns, manage distributions, and handle account linking flows.

Business Linking & Permission Grants

Before a platform can perform operations on behalf of a business (like creating campaigns or distributions), the business must explicitly grant permission to the platform. This consent-based model ensures businesses maintain control over who can access their resources and what actions they can perform.

How Permission Grants Work

A grant represents an active permission relationship between a platform and a business. When a business grants access to a platform, they specify which scopes (permissions) the platform receives. Once established, the platform can use the X-Target-Business-Id header to perform operations on behalf of that business, limited to the granted scopes.

Two Methods for Establishing Grants

There are two ways for businesses to grant permissions to your platform:

Method 1: Link Sessions (Recommended for Onboarding)

Use link sessions when you want any business to be able to connect to your platform. This is ideal for self-service onboarding flows.

Create a Link Session: Call POST /v1/platform/link-sessions with the scopes you need. You receive a unique URL and session key.
Share the Link: Direct business admins to the link session URL. This can be embedded in your onboarding flow, sent via email, or displayed in your dashboard.
Business Reviews & Approves: The business admin logs into Oncade, reviews the requested permissions, and either approves or declines.
Receive Webhook: Your platform receives a Platform.Link.Completedwebhook with the businessId and grantId. If declined, you receivePlatform.Link.Declined.
Start Operating: Use the businessId from the grant in yourX-Target-Business-Id header to perform operations on their behalf.

Tip: Include metadata when creating link sessions to track which of your users initiated the connection. This metadata is echoed back in webhooks.

Method 2: Direct Invites (For Known Businesses)

Use direct invites when you already know the business ID and want to request access directly. This is useful for partnership scenarios or when migrating existing relationships.

Send an Invite: Call POST /v1/platform/invites with the targetbusinessId and requested scopes.
Business Reviews: The business receives a notification and can review the invite in their Oncade dashboard.
Business Responds: They approve or decline the invite. On approval, a grant is automatically created.
Start Operating: Once approved, use the businessId in yourX-Target-Business-Id header to perform operations.

Managing Grants

Use GET /v1/platform/grants to list all active grants — businesses that have opted in to your platform. Each grant includes the businessId, the scopes they granted, and when the grant was created.

Either party can revoke a grant at any time. If your platform needs to update the permissions for a business (e.g., requesting additional scopes), you can revoke the existing grant viaPOST /v1/platform/grants/{grantId}/revoke and send a new invite or link session with the updated scope requirements.

Scope Intersection

The operations you can perform on behalf of a business depend on the intersection of:

Platform scopes: Scopes approved for your platform by Oncade
API key scopes: Scopes assigned to your specific API key
Grant scopes: Scopes the business granted to your platform

For example, if your platform has campaign:create approved, your API key includescampaign:create, but a business only granted campaign:read, you can only read their campaigns — not create new ones. Typically you will be requesting all scopes from a business. Scope granularity is provided for key level access rather than platform level access.

API Host

Common Headers

Every request must include the Authorization header with Bearer <platform_api_key> and X-Oncade-API-Version (defaults to v1). Business operations require X-Target-Business-Id from an active grant. Campaign operations (e.g. wallet balance, link details) require X-Campaign-Id. For POST, PUT, and PATCH requests, supply an Idempotency-Key to safely retry requests without creating duplicates.

Scopes

Platform API keys have scopes that determine what operations they can perform. Scopes are requested when creating keys and must be approved by Oncade (auto-approved in test environment).

Management Scopes (Auto-approved)

platform:read - View platform information
platform.key:manage - Manage API keys
platform.invite:manage - Manage business invites
platform.grant:manage - Manage business grants
platform.scope:request - Request new permission scopes

Business Operation Scopes (Require Approval)

Campaigns: campaign:create, campaign:read, campaign:update, campaign:delete, campaign:start, campaign:stop, campaign:payout-wallet:balance, campaign:users:link:read, campaign:users:link:create, campaign:users:link:remove, campaign:users:link:static campaign:users:wallet:read, campaign:events:create, campaign:funds:create, campaign:funds:read
Split Templates: splitTemplate:create, splitTemplate:read, splitTemplate:update, splitTemplate:delete
Distributions: distribution:create, distribution:read, distribution:funds:create, distribution:funds:read
Gifts: gift:create, gift:read
Invoices: invoice:create, invoice:read, invoice:update, invoice:send, invoice:cancel
Business Management: business:create, business:read, business:update, business:wallet:balance
Lookup: lookup:emails

Get Platform InfoGET

/v1/platform/me

Get the current platform's information including approved and pending scopes.

Required scope: platform:read

curl -X GET "https://oncade.gg/api/v1/platform/me" \
  -H "Authorization: Bearer PLATFORM_API_KEY" \
  -H "X-Oncade-API-Version: v1"

Example Response

{
  "platformId": "platform_abc123",
  "name": "My Platform",
  "description": "Platform description",
  "status": "active",
  "approvedScopes": [
    "platform:read",
    "campaign:create"
  ],
  "pendingScopes": [],
  "keyInfo": {
    "keyId": "key_xyz789",
    "environment": "test",
    "activeScopes": [
      "platform:read"
    ],
    "requestedScopes": [
      "platform:read",
      "campaign:create"
    ]
  }
}

Header	Description
`x-oncade-signature`	HMAC-SHA256 signature of the payload
`x-oncade-event`	Event type (e.g., `Platform.Link.Completed`)
`x-oncade-platform-id`	Your platform ID

Platform API Reference

Business Linking & Permission Grants

How Permission Grants Work

Two Methods for Establishing Grants

Method 1: Link Sessions (Recommended for Onboarding)

Method 2: Direct Invites (For Known Businesses)

Managing Grants

Scope Intersection

Common Headers

Scopes

Management Scopes (Auto-approved)

Business Operation Scopes (Require Approval)

Get Platform InfoGET

Example Response

Request Additional ScopesPOST

Example Response

List API KeysGET

Example Response

Create API KeyPOST

Example Response

Get API Key DetailsGET

Example Response

Revoke API KeyDELETE

Example Response

Rotate API KeyPOST

Example Response

List Link SessionsGET

Example Response

Create Link SessionPOST

Example Response

Get Link SessionGET

Cancel Link SessionDELETE

Example Response

List GrantsGET

Example Response

Revoke GrantPOST

Example Response

List InvitesGET

Example Response

Send Direct InvitePOST

Example Response

Cancel InvitePOST

Example Response

List CampaignsGET

Example Response

Create CampaignPOST

Example Response

Get CampaignGET

Update CampaignPATCH

Delete CampaignDELETE

Create Campaign Link SessionPOST

Example Response

Get Campaign Link Session DetailsGET

Example Response

Create Campaign Link InvitePOST

Example Response

List Campaign Link InvitesGET

Example Response

Update Campaign Link InvitePATCH

Example Response

Revoke Campaign Link InviteDELETE

Example Response

Record Campaign EventPOST

Example Response

Start CampaignPUT

Example Response

Stop CampaignPUT

Example Response

Create Fund SessionPOST

Example Response

Remove Campaign Account Link (Leave Campaign)POST

Example Response

List Campaign Linked UsersGET

Example Response

Get Fund SessionGET

Example Response

Get Campaign User Wallet BalanceGET

Example Response

Get Campaign Payout Wallet BalanceGET

Example Response