Skip to main content
Applications give backend services a single tenant-level identity for calling Occtoo. An Application is a machine-to-machine OAuth client with a client ID and client secret. You configure its access once, then use the OAuth 2.0 client credentials flow to request short-lived access tokens. Use an Application for unattended integrations such as services, scheduled jobs, command-line tools, and agents. One Application can ingest data, consume tenant events, and call one or more protected destination APIs.
Preferred application model: Tenant-level Applications are intended to supersede legacy data-provider and per-destination-version applications. They provide one identity and one access model across ingest, events, and destinations, making access easier to configure, review, and change. Use them for new integrations and migrate existing integrations when practical.
Keep the client secret on a trusted server. Do not put it in browser code, mobile applications, source control, or client-side configuration.

How access works

Application access has three dimensions:
  • APIs define which API audiences the Application can request. A protected destination API version has its own audience.
  • Scopes define what the Application can do in the tenant API, such as write source data or read events.
  • Resources restrict a capability to Occtoo resources. For example, an Application with write:sources can be limited to selected sources or allowed to use every current and future source.
A source ID is not an OAuth scope. You select allowed sources when configuring the Application. The token request only asks for the write:sources capability. For destinations, you can authorize a specific protected API version, every version of one destination, or all destinations. Broader destination selections also apply to matching API versions created later.
Legacy data-provider and per-destination-version credentials remain supported for compatibility while existing integrations migrate.

Request an access token

You need these values from the Application:
  • Client ID
  • Client secret
  • Tenant ID for tenant API access
  • API version ID for each protected destination API you want to call
Every direct token request must include an audience. One Application can be authorized for several APIs, but each token targets one audience. Request a separate token for each API you call, using the same client credentials. The examples below use the production token endpoint, https://auth.occtoo.com/oauth2/token. Use the authentication domain provided for your Occtoo environment when working outside production.

Try it

Request a destination, ingest, or events token in the interactive API playground.
Set the values as environment variables before running the examples:
A successful request returns a response similar to:

Code examples

Each example defines a reusable token helper and requests an ingest token. The commented calls show how to request a destination token, each Events API scope, or all scopes enabled for the tenant audience. The TypeScript example uses the server-side fetch API available in Node.js 18 and later. The Python example requires requests. The Rust example requires reqwest, serde, and tokio.
Cache and reuse the token until shortly before expires_in elapses. Then request a new one.

Access a destination API version

Request a token whose audience is the destination API version ID: In Try it, set audience to the API version ID and leave scope empty.
Do not use the destination ID as the audience. Each protected API version validates its own audience, so a tenant API token cannot be used to call it. The Application must also be authorized for that API version through its API access configuration. See Call a destination API for destination URLs and request examples.

Access the Ingest API

Request the write:sources scope using your Tenant ID as the audience: In Try it, set audience to the Tenant ID and scope to write:sources.
The Application can ingest only into the sources selected in its resource access configuration. Selecting all sources includes sources created later. See the Ingest API reference for endpoints and payloads.

Access the Events API

Use your Tenant ID as the audience. Choose the narrowest scope that covers the transports your integration needs. In Try it, set audience to the Tenant ID and use read:events, read:events:pull, or read:events:sse as the scope.
Use read:events for both pull and SSE access.
See the Events API reference and SSE guide for request and resume behavior.

Request all granted tenant scopes

The scope parameter is optional for the tenant audience. If you omit it, the token contains every tenant API scope enabled for the Application:
Prefer an explicit scope for integrations that need only one capability. This limits what a leaked token can do without changing the Application’s broader configuration.

Use the token

Send the access token as a bearer token with every protected API request:
Treat the token like a secret. Do not log it or persist it longer than necessary.

Troubleshooting

  • unauthorized_client: The Application is not authorized for the requested audience.
  • invalid_scope: The scope is not enabled for the Application, or it does not belong to the requested audience.
  • 401 Unauthorized from an API: The token is missing, expired, malformed, or intended for another audience.
  • 403 Forbidden from an API: The token is valid, but the Application lacks the required scope or access to the requested resource.