Getting Started for Platforms

This page is for engineers building on the Platform API. It covers the steps that come before every other guide: creating a platform, generating your first API key, making an authenticated call, and moving from test to live.

If you are running your own business on Oncade Pay rather than building an integration, read Getting Started instead.

1. Create a platform

Platforms are created in the developer portal at dev.oncade.xyz. Sign in with your work email address, open Platforms in the sidebar, and choose Create Platform.

A platform is owned by a business, so select the business you are working in before you start. If you do not have one yet, create it first. You need an editor role or higher on that business. There is no verification requirement to create a platform or generate keys, though the businesses you eventually move money for do have to complete their own verification.

The create form asks for:

• Platform Name. Required. How your integration is identified.
• Description. Optional. What the platform does.
• Contact Email. Required. Where scope approval notices and alerts are sent.
• Environment. Required. Test or Live, and it cannot be changed after creation. See environments below.
• Business Scopes. Optional. The business permissions your integration needs.

A newly created platform starts with a pending status and is automatically granted access to the business that owns it, so you can build against your own business right away without waiting for anyone to approve a grant.

2. Generate your first API key

Open your platform and go to the API Keys tab, then choose Create Key. Give it a label so you can tell keys apart later, and select the scopes the key should carry. At least one scope is required. The key inherits the platform's environment, so there is nothing to choose there.

The full key value is shown once, in the API Key Created dialog. Copy it before you close the dialog. Oncade stores only a hash of the key, so it cannot be shown again. If you lose it, revoke the key and create a new one.

Keys look like oncade_platform_test_... or oncade_platform_live_.... Store the value in your secret manager and read it from an environment variable. Never put it in client-side code, a repository, or a browser request.

Everything else about keys, including listing, revoking, and rotating with a grace period, is available over the API once you hold a key. See API key management. The portal is the only place you can create the first one.

3. Know your way around the portal

Each platform in the developer portal has its own set of tabs. These are the ones you will use while integrating.

Set your webhook URL under Settings before you go far into the build. Most flows report their outcome by webhook rather than in the response body. While you are there, generate the webhook secret. Like an API key it is shown only once, and you need it to verify the signature on every event you receive. See the webhooks section of the API reference for the event list and a signature verification example.

4. Test and live environments

A platform belongs to one environment, chosen when you create it, and every key you generate inherits that environment. There is no separate test host. All requests go to https://www.oncade.gg and the environment travels with the key, so you switch environments by switching which key you send.

The environment is fixed when the platform is created and cannot be changed afterwards, so in practice you create two platforms: one in test to build against, and one in live when you are ready for real money movement. Keys, scope approvals, grants, and webhook settings are all separate between the two.

Scopes that begin with platform., such as platform:read and platform.key:manage, are always approved in both environments. Only business operation scopes, such as invoice:create and distribution:create, need review on a live platform.

5. Make your first authenticated call

GET /v1/platform/me is the cheapest way to confirm your key works. It reads your platform record and needs only the platform:read scope, which every platform has.

Every request carries an Authorization header with Bearer <platform_api_key> and an X-Oncade-API-Version header, which defaults to v1.

curl -s \
  -H "Authorization: Bearer $ONCADE_PLATFORM_KEY" \
  -H "X-Oncade-API-Version: v1" \
  https://www.oncade.gg/api/v1/platform/me

A successful call returns 200 with your platform record:

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

Read the response as a checklist:

• keyInfo.environment confirms which environment the key you just used belongs to.
• keyInfo.activeScopes is what this key can actually do right now.
• approvedScopes is what your platform is allowed to do at all.
• pendingScopes is what you have asked for and Oncade has not yet approved.

A scope you requested that appears in pendingScopes but not in activeScopes will fail with a permission error until it is approved. A 401 means the key was rejected, usually because it was copied incompletely or has been revoked.

Once this call succeeds you have a working integration surface. Business operations add two headers on top: X-Target-Business-Id for the business you are acting for, and an Idempotency-Key on every POST, PUT, and PATCH so retries do not create duplicates.

6. Request live scopes

Build and rehearse the full flow in test first. When it works end to end, move to live in this order:

1. Create a live platform. In the developer portal, choose Create Platform again and set the environment to live. Select the same business scopes your test integration ended up using.
2. Request the scopes you need. On the live platform, the Scopes tab shows business scopes under pending approval. Use Request Scopes to add any you missed. You can also do this over the API with POST /v1/platform/me/scopes.
3. Wait for approval. Oncade reviews business scopes on live platforms. Approved scopes move from pending to approved and the platform becomes active. Ask only for what you use, since a narrower request is quicker to review.
4. Generate a live key. Create the key on the live platform and store it separately from your test key. A live key only works with scopes that are already approved, so create it after approval or re-check GET /v1/platform/me before you rely on it.
5. Point your webhook URL at production. Set it under Settings on the live platform. It is a separate setting from your test platform.
6. Connect real businesses. In test you mostly worked against your own business. In live, each business you act for needs a grant. See the business linking and grants overview for link sessions and invites.

Getting help

Integration questions go through your Oncade account manager. They will connect your engineers directly with Oncade developers in a shared Slack channel, which is the supported path for integration support. Use it for scope approvals that are taking longer than expected, unexpected API responses, webhook delivery problems, and anything you need reviewed before you launch.

When you get in touch, include your platformId, the environment, the endpoint and HTTP status you saw, and the time of the request. That is usually enough to find the request on our side without further back and forth.

Next steps

• Embedded Finance overview, for how the pieces fit together
• Business Onboarding guide
• Invoicing guide
• Payouts & Distributions guide
• Platform API Reference