# ResearchCave Developers

> A starting point for AI assistants integrating with ResearchCave on behalf of an authorized user or organization.

## Discover available APIs

- [API catalog](https://developers.researchcave.com/integrations): Discover current integrations and follow their documentation links for endpoints, request schemas, supported actors, and permissions. APIs may be added or removed; do not assume a fixed service list or guess API URLs.
- [Sign-in and personal keys](https://login.researchcave.com/Dashboard/ApiKeys): Account authentication and personal API-key management.
- [Organizations](https://org.researchcave.com/): Organization membership, permissions, and organization API-key management.

A catalog listing does not grant access. Use the resources currently offered by the key-creation interface and the target API's documentation. If documentation is unavailable, ask for it rather than inventing endpoints.

## Choose the correct identity

- Personal automation: Have the user create a key through [Create key](https://developers.researchcave.com/CreateKey), selecting only the required API resources. It acts as that user and remains subject to their current account status and roles.
- Organization automation: Have an authorized member create a key in the organization's API-key settings, selecting available resources, optional permissions, expiry, and applicable spending limits. The credential acts for its fixed organization; it does not impersonate a member. Only explicitly supported APIs accept it.
- A person acting for an organization still needs current membership and permission for the operation. Selecting an organization or knowing its ID grants no authority. Organization permissions and spending rules are separate from API access and scopes.

## Call an API

Follow the current authentication documentation linked from the catalog. API keys are exchanged at the login authority for short-lived access tokens using OAuth token exchange; they are not bearer access tokens for arbitrary APIs.

The exchange uses `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`, `subject_token_type=urn:researchcave:params:oauth:token-type:api-key`, the key as `subject_token`, and exactly one `audience` matching an authorized API resource. Follow the documented client requirements; request only granted scopes when needed. A key may cover multiple resources, but each token targets one resource.

Send the returned access token as `Authorization: Bearer <access_token>` only to its intended API over HTTPS. Respect expiry and authorization failures; do not switch identities to bypass denied access. Credential and security management require an interactive user.

## Handle credentials safely

Store newly issued keys in a secret store. Never place keys or tokens in URLs, source code, logs, or assistant messages. Revocation prevents new token issuance; existing access tokens may remain valid until expiry. Use the management interface to revoke exposed or unused keys.