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:sourcescan be limited to selected sources or allowed to use every current and future source.
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
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.
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-sidefetch API available in Node.js 18 and later. The Python example requires requests. The Rust example requires reqwest, serde, and tokio.
- cURL
- C#
- TypeScript
- Python
- Rust
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, setaudience to the API version ID and leave scope empty.
Access the Ingest API
Request thewrite:sources scope using your Tenant ID as the audience:
In Try it, set audience to the Tenant ID and scope to write:sources.
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, setaudience to the Tenant ID and use read:events, read:events:pull, or read:events:sse as the scope.
- All events
- Pull
- SSE
Use
read:events for both pull and SSE access.Request all granted tenant scopes
Thescope parameter is optional for the tenant audience. If you omit it, the token contains every tenant API scope enabled for the Application:
Use the token
Send the access token as a bearer token with every protected API request: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 Unauthorizedfrom an API: The token is missing, expired, malformed, or intended for another audience.403 Forbiddenfrom an API: The token is valid, but the Application lacks the required scope or access to the requested resource.