Skip to main content

Mercury Setup

Connecting Mercury to Caddi with a custom OAuth client

Mercury issues OAuth clients only to integrations it has approved. This guide covers requesting a client from Mercury and adding its credentials to Caddi.

Before you start

You'll need:

  • Approval from Mercury for OAuth access. Mercury reviews each request, and timelines vary. Step 2 covers how to request it.

  • A GPG key pair. Mercury asks for your public key so it can send your client credentials securely. Keep the matching private key; you need it to decrypt the credentials in Step 2.

  • Owner or Admin access to your Caddi organization

Step 1: Copy the redirect URL from Caddi

Copy the redirect URL now. Mercury asks for it after it approves your request.

  1. In Caddi, open Settings, then Integrations.

  2. Under Connectors you can configure, find Mercury - Custom OAuth2 Client and click Configure.

  3. Click Copy redirect URL. It is https://app.trycaddi.com/oauth-callback.

Step 2: Request an OAuth client from Mercury

  1. Submit Mercury's OAuth access request form. Mercury asks for your company name, website, and address, a short company description, details about the product you plan to integrate with Mercury, and how you plan to use Mercury's API.

  2. If Mercury approves the request, it asks for technical details. Provide:

    • The redirect URL you copied in Step 1, as the redirect URI for your production client

    • Links to your terms of service, privacy policy, and logo

    • Your GPG public key

    • A request that your production client include the offline_access scope in its configuration

  3. Mercury then sends a client ID and client secret for your production client, plus credentials for a separate test client for Mercury's sandbox. Decrypt Mercury's message with your GPG private key, then keep the production client ID and client secret for Step 3. Do not use the sandbox test client; Caddi connects to Mercury's production API.

Do not send this secret by email, chat, or a support ticket. Paste it straight into Caddi in Step 3, or keep it in a password manager until you do.

Step 3: Configure Mercury in Caddi

  1. In Caddi, open Settings, then Integrations.

  2. Under Connectors you can configure, find Mercury - Custom OAuth2 Client and click Configure.

  3. Fill in the fields:

    • Client ID: the production client ID Mercury sent you.

    • Client Secret: the production client secret Mercury sent you.

    • OAuth Scopes: leave blank to use Caddi's default scopes. Caddi requests offline_access when you connect, and it is required so Caddi can refresh the connection.

    • API Base URL: optional. Enter it only if Mercury supplied an API base URL for your integration.

  4. Click Save Configuration.

Step 4: Confirm the connection

  1. In Caddi, open Integrations in the left sidebar.

  2. Find Mercury - Custom OAuth2 Client and click Connect.

  3. Sign in to Mercury and approve the request. You'll be returned to Caddi with the connection active.

If you're not going to be an everyday user of Caddi, you can disconnect after confirming the connection works.

Sources

Related Articles
Did this answer your question?