> For the complete documentation index, see [llms.txt](https://docs.countercyclical.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.countercyclical.io/developers/oauth-2.0-applications.md).

# OAuth 2.0 Applications

## 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

{% hint style="warning" %}
Implicit Flow is intentionally unsupported due to modern OAuth security recommendations. You can learn more here:

<https://oauth.net/2/grant-types/implicit/>
{% endhint %}

| 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](https://dashboard.countercyclical.io/settings/workspace/developers/oauth)

### 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

{% hint style="info" %}
Secrets are displayed once and must be securely stored.&#x20;

We recommend leveraging [environment variables](https://en.wikipedia.org/wiki/Environment_variable) as a best practice.
{% endhint %}

## 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

```bash
GET /oauth/authorize
```

#### Example Request

```bash
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

```bash
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

```bash
POST /oauth/revoke
```

### Example Request

```bash
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

```json
{
    "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

```bash
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

```json
{
    "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

{% hint style="info" %}
Verification status does not imply endorsement of investment activity, recommendations, or financial outcomes.
{% endhint %}

### 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.countercyclical.io/developers/oauth-2.0-applications.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.