DEVELOPERS
RIIW developer platform overview
Choose between service accounts, OAuth applications, and webhooks for a secure RIIW integration.
RIIW provides a versioned Public API for reading and changing organization data, OAuth for applications used by multiple people or customers, and signed webhooks for receiving changes without polling. Each integration is bound to one organization and receives only the scopes approved for it.
Members can discover organization applications from the selected organization's Apps area. Organization owners manage shared connections from protected Apps & integrations settings. Each user manages personal connections separately under My apps. Organization-owned tokens and endpoint delivery live separately under Organization settings → API & Webhooks. Custom app registration remains under Developer Settings.
Choose an integration method
Use a service account for automation owned by one organization, such as an internal reporting job or task synchronizer. An organization administrator creates the credential, chooses its scopes, and copies the token once.
Use an OAuth application when a person should authorize a third-party product. The application redirects an organization administrator to RIIW, requests registered scopes, and receives short-lived access tokens through Authorization Code with PKCE.
Use a webhook endpoint when your system needs near-real-time notifications. Webhooks belong to a service account or OAuth installation, carry signed metadata, and use retry and dead-letter handling.
| Requirement | Recommended option |
|---|---|
| Organization-owned automation | Service account |
| Customer-facing application | OAuth application |
| Event-driven synchronization | Webhook attached to a service account or OAuth installation |
API contract and boundaries
The stable customer API is served under /api/public/v1. The machine-readable OpenAPI 3.1 contract is available at GET /api/public/v1/openapi.json. Resource URLs include the organization ID; a credential cannot cross into another organization.
Public API credentials do not work on RIIW’s internal /api/v1 management routes. Browser session credentials do not work as Public API bearer tokens. Membership changes, billing, owner transfer, integration credential creation, and storage secrets remain interactive management operations and are intentionally outside the Public API.
Direct chat messages are never exposed through Public API channel access or webhook events. Applications requesting chat scopes must be granted selected active organization channels or explicitly granted all organization channels.
Before you build
- Confirm the organization plan includes the required Public API, OAuth, or Webhooks module.
- Decide who owns credential rotation and incident response.
- Request the narrowest scopes required for the integration.
- Read the OpenAPI contract instead of guessing request or response fields.
- Implement idempotency, pagination, ETag handling, rate-limit backoff, and safe secret storage before production use.
If a platform administrator temporarily pauses integrations, credentials are not revoked. API calls return a temporary service-unavailable problem and webhook deliveries remain queued until service resumes.
Next steps
- For application authorization, follow Manage App Center.
- For service accounts and endpoint delivery, follow Manage API & Webhooks.
- For organization automation, follow Create and manage API credentials.
- For third-party authorization, follow Build an OAuth application.
- For event delivery, follow Configure and verify webhooks.
- Before shipping a client, read Handle API errors, retries, and concurrency.
Never include bearer tokens, OAuth codes, refresh tokens, signing secrets, or complete webhook payloads in support tickets. Provide request IDs, event IDs, timestamps, and redacted error responses instead.