OAuth 2.0 Applications

Create custom OAuth 2.0 applications to build integrations directly into Countercyclical.

Overview

Countercyclical’s Custom OAuth 2.0 Applications framework enables institutional investment teams, allocators, family offices, private equity firms, hedge funds, RIAs, consultants, and enterprise technology teams to securely connect internal tools, automate workflows, synchronize research artifacts, and extend the platform using standardized authorization flows.

Whether you are integrating a proprietary portfolio management system, data warehouse, CRM, compliance workflow, AI agent, operational database, valuation engine, or third-party research system, Custom OAuth Applications provide granular, auditable, and workspace-scoped access to Countercyclical APIs.

Supported OAuth 2.0 Flows

Implicit Flow is intentionally unsupported due to modern OAuth security recommendations. You can learn more here:

https://oauth.net/2/grant-types/implicit/

Authorization Code + PKCE	Web applications, SPA applications, desktop clients
Authorization Code	Confidential server-side applications
Client Credentials	Server-to-server integrations and backend automation
Refresh Token	Long-lived delegated sessions
Device Authorization Flow	Internal CLI tooling and limited-input enterprise devices

Creating an OAuth Application

1: Navigate to Developer Settings

Within your workspace, navigate to Settings → Workspace -> Developers → OAuth Applications

2: Create Application

Provide:

• Application name + metadata

• Description

• Environment type

• Redirect URIs

• Allowed scopes

• Ownership metadata

• Support contact information

3: Retrieve Credentials

After provisioning, Countercyclical generates:

• Client ID

• Client Secret (confidential clients only)

• JWK configuration metadata

• Discovery endpoints

Secrets are displayed once and must be securely stored.

We recommend leveraging environment variables as a best practice.

Secret Rotation

Countercyclical supports zero-downtime credential rotation.

Recommended Rotation Policy

Client Secrets	Every 90 days
Signing Keys	Platform-managed

Applications may maintain overlapping active secrets during rotation windows.

Authorization Code Flow

The Authorization Code Flow is recommended for secure user-facing applications.

Authorization Request

GET /oauth/authorize

Example Request

GET https://api.countercyclical.io/oauth/authorize
    ?response_type=code
    &client_id=cc_client_123456
    &redirect_uri=https://app.example.com/callback
    &scope=research.read%20diligence.read&state=secure_random_state
    &code_challenge=pkce_challenge
    &code_challenge_method=S256

Authorization Response

HTTP/1.1 302 FoundLocation: 

https://app.example.com/callback
    ?code=auth_code
    &state={SECURED_RANDOM_STATE_VALUE}

---

Token Revocation

Applications and administrators may revoke active tokens.

Revocation Endpoint

POST /oauth/revoke

Example Request

POST https://api.countercyclical.io/oauth/revoke
Content-Type: application/x-www-form-urlencoded
client_id=cc_client_123456
token=ACCESS_TOKEN

Revocations propagate across distributed authorization infrastructure in near real-time.

Error Handling

Standard OAuth Errors

Error	Description
invalid_client	Invalid client credentials
invalid_grant	Invalid authorization grant
invalid_scope	Unauthorized scope requested
unauthorized_client	Client not permitted for flow
access_denied	User denied authorization
unsupported_grant_type	Unsupported grant type
rate_limit_exceeded	Request limit exceeded

Example Error Response

{
    "error": "invalid_scope",
    "error_description": "Requested scope is not permitted"
}

---

Client Credentials Flow

The Client Credentials Flow is intended for backend services and machine-to-machine integrations.

Example Request

POST https://api.countercyclical.io/oauth/token

Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=cc_client_123456
&client_secret=cc_secret_abcdef
&scope=research.read

Example Response

{
    "access_token": "eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 3600
}

---

Publishing Applications to Countercyclical's Integration Directory

OAuth applications may optionally be published to the Countercyclical Integration Directory, enabling other organizations to discover, install, authorize, and operationalize integrations across their investment workflows.

The Integration Directory is designed for institutional-grade distribution of trusted integrations, internal tooling connectors, operational extensions, AI agents, compliance systems, portfolio management connectors, research automation utilities, and enterprise workflow applications.

Platform Characteristics

• Workspace-isolated authorization boundaries

• Tenant-scoped token issuance

• Independent credential chains

• Distributed webhook infrastructure

• Environment segregation

• Granular revocation controls

• Regional authorization enforcement

Installed integrations never receive implicit cross-tenant access.

Publishing Model

OAuth applications remain private by default.

Developers may publish applications in one of two ways:

1. During Application Creation

Within the OAuth Application creation workflow:

Settings → Developer Platform → OAuth Applications → Create Application

Developers may enable:

[ ] Publish to Countercyclical Integration Directory

2. After Initial Creation

Existing applications may be published at any time from:

OAuth Application → Distribution Settings → Publish Application

Publishing is non-destructive and does not alter existing credentials, scopes, authorization flows, or installed tenants.

The Integration Directory is designed for enterprise-scale multi-tenant distribution.

Integration Directory Review Process

To preserve ecosystem reliability and institutional security standards, published integrations may undergo automated and manual review procedures.

Review Areas

Countercyclical may evaluate:

• OAuth security configuration

• Redirect URI integrity

• Scope usage patterns

• Webhook security posture

• Branding authenticity

• Application stability

• Documentation completeness

• Enterprise operational readiness

• Compliance-sensitive workflows

• Data handling characteristics

Applications handling highly sensitive operational workflows may require enhanced review.

Integration Metadata

Published integrations may expose:

Integration Name	Public integration display name
Description	Functional overview
Vendor / Team	Publishing organization
Supported Features	Functional capability summary
Scopes Requested	Required authorization scopes
Documentation Links	Integration documentation
Support Contacts	Operational support channels
Security Information	Security and compliance disclosures
Version Metadata	Published release information

Workspace administrators retain visibility into all requested permissions before installation.

Private vs Public Integrations

Private Integration	Available only within originating workspace
Public Directory Integration	Discoverable in the Integration Directory
Organization Integration (Enterprise Plans Only)	Shareable across approved organizations

Organizations may migrate integrations between visibility models without rebuilding applications.

Rescinding Published Integrations

Developers and organizations retain full ownership and control over their integrations.

At any time, publishers may:

• Unpublish integrations

• Disable new installations

• Suspend authorization flows

• Rotate credentials

• Revoke downstream access

• Delete applications entirely

Unpublishing Behavior

When an integration is rescinded from the Integration Directory:

• The integration is removed from discovery surfaces

• New installations are blocked

• Existing tenant installations may optionally remain active

• Workspace administrators with installed instances are notified

• Audit records are preserved

• Existing API access policies remain enforceable

---

Downstream Client Notifications

Countercyclical automatically notifies downstream installed tenants when material integration lifecycle changes occur.

Notification Events

Integration Unpublished	Email notification sent to affected administrators
Integration Suspension	Workspace administrators alerted
Scope Expansion	Reauthorization may be required
Credential Compromise	Security notifications distributed
Ownership Transfer	Tenant administrators informed
Integration Deletion	Final deprecation notifications distributed

Notifications are designed to support enterprise operational continuity and vendor governance requirements.

Recommended Publishing Practices

Operational Recommendations

• Publish minimal required scopes

• Maintain detailed integration documentation

• Implement graceful API degradation handling

• Version integrations conservatively

• Maintain dedicated support ownership

• Monitor webhook delivery failures

• Enforce credential rotation policies

• Provide tenant-facing changelogs

Enterprise Recommendations

• Maintain vendor security documentation

• Publish incident response contacts

• Separate sandbox and production integrations

• Support auditability requirements

• Implement environment-specific authorization boundaries

• Conduct periodic access reviews

Integration Trust & Verification

Countercyclical may apply verification indicators to integrations meeting operational, security, and reliability thresholds.

Verification Signals

• Verified publisher identity

• Security review completion

• Enterprise adoption indicators

• Documentation completeness

• Reliability metrics

• Operational support validation

• Integrations built internally & published by Countercyclical

Verification status does not imply endorsement of investment activity, recommendations, or financial outcomes.

Analytics & Operational Visibility

Publishers on the Enterprise Plan may access integration analytics including:

• Installation counts

• Authorization trends

• Active tenant metrics

• Webhook delivery health

• API consumption patterns

• Error rates

• Scope utilization

• Version adoption

Analytics visibility is constrained to the publisher’s own integrations.

---

Best Practices

Here are a couple best practices for building & deploying custom OAuth 2.0 applications for Countercyclical.

Recommended Security Practices

• Always use PKCE for public clients

• Never embed client secrets in frontend applications

• Store secrets in dedicated secret managers

• Rotate credentials regularly

• Restrict scopes to minimum required permissions

• Validate webhook signatures

• Enforce HTTPS for all redirect URIs

• Use short token lifetimes

• Monitor anomalous authentication patterns

• Isolate production and non-production environments

---

Audit Logging

All OAuth-related activity is fully auditable.

Logged Events

• Application creation

• Scope modifications

• Token issuance

• Token revocation

• Authentication events

• Failed authorization attempts

• Webhook delivery activity

• Secret rotations

• Permission escalations

Audit records are immutable and exportable.