> ## Documentation Index > Fetch the complete documentation index at: https://keyring.docs.composio.dev/llms.txt > Use this file to discover all available pages before exploring further. # Credential refresh and exchange > See how Composio refreshes provider credentials through your Keyring without receiving plaintext tokens. export const RefreshExchangeDiagram = () =>
; 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. Your application does not call this route. Composio invokes the protected exchange flow as part of operating the connected account; your application continues to use Composio tools normally. ## 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 | Party | What it can see during refresh | | ----------------------- | ---------------------------------------------------------------------------------------------- | | Composio | Exchange instructions, encrypted credential envelopes, safe metadata, and the protected result | | Your Keyring | Plaintext credential inputs and provider token fields briefly in process memory | | Your KMS | Authorized key operations and key metadata; not the provider request or token values | | Provider token endpoint | The plaintext refresh inputs required by that provider and the token it issues | | Your audit collector | Operation metadata and field dispositions; never plaintext credential values | ## 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](/deployment/overview#connect-keyring-to-composio) for authentication and network setup, and [Encryption and key hierarchy](/concepts/encryption_and_keys) for the keys used to protect credentials.