Credential refresh and exchange

When a connected account needs a new access token, Composio routes the token exchange through the Keyring running in your environment. The provider can issue new credentials, but their plaintext form does not return to Composio.

​

Follow one refresh

The values in the animation are masked examples. Keyring does not place plaintext credentials in its request or audit logs.

​

What the exchange route does

POST /api/v1/exchange is a protected service-to-service route between the Composio backend and your Keyring. It is not a Composio admin endpoint and it is not an API that customer applications need to integrate with. Composio uses the exchange flow for provider token operations such as initial token issuance, OAuth refresh, and revocation. Keeping these operations separate from ordinary tool forwarding lets Keyring apply stricter destination and response-handling rules.

​

1. Composio sends an encrypted instruction

The signed request identifies the toolkit, the approved provider token endpoint, and the exchange to perform. Credential inputs—such as a refresh token or client secret—arrive as encrypted references. The request also carries a data-key envelope that Keyring can use to protect any secrets returned by the provider.

​

2. Keyring verifies before opening a secret

Keyring verifies Composio’s signature and your organization audience, then checks the bundled policy. The policy must allow the toolkit, exact token endpoint, request fields, response fields, and redirect behavior. A failed check ends the request before plaintext is created. After those checks pass, Keyring asks your KMS to authorize the required key operation. Your KMS root key remains in the KMS; only Keyring’s workload identity receives permission to use it.

​

3. The provider performs the refresh

Keyring resolves the encrypted refresh inputs in memory and constructs the provider request. For a Gmail connection, the only external destination that receives those plaintext inputs is Google’s approved OAuth token endpoint. The provider returns a response that can contain both secrets and ordinary metadata—for example, a new access token alongside its expiry and token type.

​

4. Keyring protects the response field by field

Before a successful provider response leaves your environment, Keyring encrypts credential fields such as access_token and refresh_token. Safe metadata such as expires_in and token_type can remain plaintext so Composio can schedule the next refresh and operate the connection. The toolkit policy decides which fields are sensitive. A request cannot downgrade a protected token field to plaintext. If Keyring cannot parse and protect a successful response as required, it fails closed instead of returning unknown plaintext.

​

5. The operation becomes auditable

Keyring records the toolkit, provider destination, exchange operation, policy result, and the disposition of returned fields. It records that a field was encrypted or allowed as metadata—not the field’s secret value. When required audit durability is enabled, the protected result is not returned until your collector acknowledges the audit event. Composio then receives encrypted credential fields plus any permitted non-secret metadata.

​

Who can see each part

​

Why ordinary forwarding cannot do this

Keyring rejects token endpoints on the ordinary provider-forwarding path. That prevents a normal tool request from being repurposed to mint or refresh a credential without the exchange-specific checks. The exchange route adds three guarantees:

1. The destination must be an approved token endpoint for the named toolkit.
2. Sensitive inputs are resolved only after authentication and policy checks pass.
3. Secret response fields are encrypted before the successful response leaves Keyring.

​

What you configure

You do not configure individual refresh jobs. Your deployment provides the controls the exchange flow depends on:

• Composio authentication settings, including your organization ID as AUTH_AUDIENCE;
• a workload identity with narrowly scoped access to your KMS keys;
• the bundled provider policy, or a reviewed custom policy when required; and
• an audit collector and durability mode appropriate for your security requirements.

See Deployment overview for authentication and network setup, and Encryption and key hierarchy for the keys used to protect credentials.