> ## Documentation Index > Fetch the complete documentation index at: https://support.affinity.co/llms.txt > Use this file to discover all available pages before exploring further. # How to Create and Manage OAuth Apps > Create an OAuth app in Manage Apps so your team can connect a tool to Affinity by signing in, without sharing an API key. > [!NOTE] > > **How-to** — task-oriented recipe. **Last Updated:** October 29, 2026 **Object Tags:** OAuth Apps, Manage Apps, API, Integrations, Admin, Security ## Overview An OAuth app lets people in your organization connect a tool to Affinity by signing in with their own Affinity account. Nobody has to create, paste, or share an API key. Each person approves the connection on an Affinity consent screen, and the tool then acts as that person, with the same data access they already have. An OAuth app you create belongs to your organization. Only people in your organization can authorize it. **Use an OAuth app** when a tool acts on behalf of individual people, and each person should sign in as themselves. For example, an internal dashboard your deal team signs into, an in-house assistant built on the Affinity MCP server, or an external application that integrates with Affinity. **Use an [API key](https://support.affinity.co/s/article/How-to-create-and-manage-API-keys.md)** when a script or integration runs as one account in the background, for example a nightly data sync. ## Prerequisites **Plan:** Scale, Advanced, or Enterprise. **Permissions required:** * **Manage all OAuth apps** to create, edit, or revoke OAuth apps. Enterprise Admins and Admins have it by default. * **Manage IP allowlist** to set or change an app's IP allowlist, if your organization restricts who can set IP allowlists. Enterprise Admins can grant these permissions to other roles under **Settings → Users and Permissions → Roles**, in the **APIs / Integrations** section. **Before you start:** * Ask the developer building the tool for its **redirect URI** (the address Affinity sends people back to after they sign in) and whether it runs on a server or on people's own devices. * Send the developer the [OAuth Apps and MCP Clients developer guide](https://developer.affinity.co/pages/external-api-v2/oauth-apps). It covers Affinity's OAuth endpoints and how to connect. * Decide which **scopes** the tool needs. Give it the fewest that work. ## Part 1: Create an OAuth app ![Animation: New App, then OAuth App, then Add App, then the Client Secret Created window, then the new app in the Manage Apps table](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/oauth-create-flow.gif?s=25421ed1a90d3a12fe350a216119b8e9) ### Step 1: Open Manage Apps 1. Click **Settings** in the left navigation. 2. Click **Manage Apps**. 3. Click **New App**, then choose **OAuth App**. ![The New App menu in Manage Apps with API Key, OAuth App and Client URL (CIMD)](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/new-app-menu.png?fit=max\&auto=format\&n=ukyIrSunOUGxUKDY\&q=85\&s=89cc7b8509674fe3a5bcdf38c74e9e01) ### Step 2: Fill in the app details The **Add New OAuth App** form has four sections. **App Information** | Field | What to enter | | - | - | | **Name** (required) | 3–50 characters. People see this name on the consent screen, so make it recognizable. | | **Client Type** (required) | **Public** (the default) for a tool that runs on people's own devices, such as a desktop, mobile, or single-page web app. **Confidential** for a tool that runs on a server you control. A confidential app gets a client secret; a public app does not. | > [!WARNING] > > **You can't change the client type later.** If you pick the wrong one, revoke the app and create a new one. **Client Details** | Field | What to enter | | - | - | | **Description** (required) | Up to 255 characters. What the tool does and who owns it. | | **Icon URL** (optional) | A link to the tool's icon, for example `https://example.com/icon.png`. | | **Website URL** (optional) | The tool's website. The app name on the consent screen links here. | **OAuth Details** | Field | What to enter | | - | - | | **Redirect URIs** (required) | One full URL per line, for example `https://example.com/callback`. Get these from the developer. | | **Allowed Scopes** (required) | What the tool may do. See [Scopes](#scopes) below. | | **Default API Version** | New apps default to the latest version. Leave it unless the developer asks for a specific one. | **IP Allowlist** (optional) **Allowed IP Addresses and Ranges:** one IP address or range per line, up to 100. Leave it blank to allow any address. When it's set, requests from any other address are rejected. ![The Add New OAuth App form with App Information, Client Details, OAuth Details and IP Allowlist sections](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/add-new-oauth-app-form.png?fit=max\&auto=format\&n=ukyIrSunOUGxUKDY\&q=85\&s=f78fc8b36baa4885a76d10f48ed38f2d) ### Step 3: Add the app 1. Click **Add App**. 2. **Confidential apps only:** a **Client Secret Created** window shows the client secret. Click **Copy client secret** and store it somewhere secure, such as your password manager, then share it with the developer securely. > [!WARNING] > > **The client secret is shown once.** Affinity doesn't store it in a form it can show you again, and you can't reset it. If it's lost, revoke the app and create a new one. Everyone who connected the old app will need to connect again. ![The Client Secret Created window, with the secret hidden](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/client-secret-created.png?fit=max\&auto=format\&n=ukyIrSunOUGxUKDY\&q=85\&s=da792688c12d5fc23b42f303c917e724) ### Step 4: Give the developer the Client ID 1. In **Manage Apps**, open the app you created. 2. Copy the **Client ID** from the **OAuth Details** card. 3. Send the developer the Client ID (and, for a confidential app, the client secret). The developer uses these to connect the tool. For the technical details, point them to the developer guide: [OAuth Apps and MCP Clients](https://developer.affinity.co/pages/external-api-v2/oauth-apps). ![An OAuth app in Manage Apps showing the Overview and OAuth Details cards, including the Client ID](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/oauth-app-details.png?fit=max\&auto=format\&n=ukyIrSunOUGxUKDY\&q=85\&s=f61455687ca7e660eb3298a241623b69) ## Add an MCP client by its Client URL (CIMD) Some MCP clients publish their own client details at a URL, called a Client ID Metadata Document (CIMD). You can add one of these by its URL instead of filling in the form. 1. Go to **Settings → Manage Apps**. 2. Click **New App**, then choose **Client URL (CIMD)**. 3. Paste the URL the developer or vendor gives you into **Client URL**, and click **Preview**. 4. Check the details Affinity fetched, such as the **Hostname**, **Name** and **Redirect hosts**. Affinity doesn't verify them, so only add a client you trust. 5. Choose the **Allowed Scopes**, and optionally set an **IP Allowlist**. 6. Click **Add App**. If the vendor changes its client details, click **⋯** on the app's row and choose **Refresh Metadata**. To remove the client, revoke it as described in Part 3. ![The Add App by Client URL (CIMD) page after Preview, showing the hostname, name, logo URL and redirect hosts](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/add-app-by-client-url.png?fit=max\&auto=format\&n=ukyIrSunOUGxUKDY\&q=85\&s=dbca00da62f9ff6534924aab29587f7c) ## Scopes Scopes decide what the tool can do on each person's behalf. A tool never gets more access than the person who authorized it. | Scope | Description in Affinity | Use it when | | - | - | - | | `api` | Access to all Affinity APIs on your behalf | The tool reads and writes data through the Affinity API. | | `api.read` | Read-only access to Affinity APIs on your behalf | The tool only reads data. | | `mcp` | Read and write data in Affinity via the MCP server | The tool is an AI assistant or agent that connects through [Affinity MCP](https://support.affinity.co/s/article/Getting-started-with-Affinity-MCP.md). | | `mcp.read` | Read access to data in Affinity via the MCP server | The same, read-only. | | `offline_access` | Continuous access to your Affinity data while logged out | The tool runs in the background, when the person isn't signed in to Affinity. | > [!TIP] > > `mcp` covers the API as well, but `api` does not cover MCP. If the tool connects through the MCP server, it needs `mcp` or `mcp.read`. ![The Allowed Scopes list with api, api.read, mcp, mcp.read and offline\_access](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/allowed-scopes.png?fit=max\&auto=format\&n=ukyIrSunOUGxUKDY\&q=85\&s=cad227e70f8fb7be0685800af387b29f) ## What your team sees when they connect The first time someone uses the tool, it sends them to an Affinity sign-in page, followed by a consent screen: * The screen names the app and the Affinity organization it will connect to. * It lists what the app will be able to do, one checkbox per scope. Everything is checked by default, and the person can uncheck any scope they don't want to grant. * They click **Allow Access** to connect, or **Cancel**. ![The Affinity consent screen asking the person to allow access, with one checkbox per scope and an Allow Access button](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/consent-screen.png?fit=max\&auto=format\&n=ukyIrSunOUGxUKDY\&q=85\&s=7b109f388bb170d333f37783717addb3) ## Part 2: View and edit an OAuth app 1. Go to **Settings → Manage Apps**. OAuth apps show **OAuth** in the **Type** column. 2. Click the app to open it. You'll see the **Client ID**, **Redirect URIs**, **Allowed Scopes**, and **Allowed IP Addresses and Ranges**, plus who created it, when, its **Client Type**, and its **Default API Version**. 3. To change it, click **Edit Details**, make your changes, and click **Save Changes**. You can change the name, description, icon URL, website URL, redirect URIs, allowed scopes, default API version, and IP allowlist. You can't change the client type or see the client secret again. ## Part 3: Revoke an OAuth app Revoke an app when the tool is no longer used, when its client secret may have been exposed, or when you need to cut off its access. 1. Go to **Settings → Manage Apps**. 2. Open the app, or click **⋯** on its row. 3. Click **Revoke App**. 4. Read the confirmation and click **Revoke App**. Revoking: * Immediately stops all API access for the app. * Disconnects everyone in your organization who connected it. * Can't be undone. The app is removed, and its Client ID stops working. To restore access, create a new app, give the developer its new Client ID, and have your team connect again. ![The Revoke App confirmation, listing what revoking does](https://mintcdn.com/support-affinity/ukyIrSunOUGxUKDY/images/admin-apps-apis/how-to-create-and-manage-oauth-apps/revoke-app.png?fit=max\&auto=format\&n=ukyIrSunOUGxUKDY\&q=85\&s=f13390e2842446b39bc75eab4f0fc058) ## Current limitations * The client secret can't be viewed again or reset. To replace it, revoke the app and create a new one. * There's no way to pause an app. Revoking removes it. * The client type can't be changed after the app is created. * An IP allowlist applies to Affinity API v2 only. * Requests from OAuth apps count toward your organization's API usage and rate limits, the same as API keys. To see each app's requests, go to **Settings → Usage** ([How to explore your API usage](https://support.affinity.co/s/article/How-to-explore-API-usage.md)). * You can't yet limit an app to certain roles or people. Anyone in your organization can authorize an app you've created. ## FAQ **Is an OAuth app the same as connecting Claude or ChatGPT to Affinity?** Yes. Claude, ChatGPT, Notion and the other AI tools listed in **Settings → Affinity MCP** are built-in OAuth connections. An admin turns them on or off on that page, and they connect through pre-approved connectors for the Affinity MCP. You'll see these apps in **Manage Apps** alongside the apps you create. Create an OAuth app for any tool you use that isn't supported out of the box. See [Getting started with Affinity MCP](https://support.affinity.co/s/article/Getting-started-with-Affinity-MCP.md). **What's the Client URL (CIMD) option in the New App menu?** It adds an MCP client that publishes its own client details at a URL, so you don't fill in the form by hand. Click **New App**, choose **Client URL (CIMD)**, paste the URL the developer gives you, and click **Preview** to check the details before adding it. See the [developer guide](https://developer.affinity.co/pages/external-api-v2/oauth-apps) for more. **Can the tool see more than the person who connected it?** No. The tool gets the same data access as the person who authorized it, limited further by the scopes you allowed and the person granted. **Who can see our OAuth apps?** Anyone with **Manage all OAuth apps**, **Manage all API keys**, or **Generate an API key** can see the Manage Apps table. Only people with **Manage all OAuth apps** can create, edit, or revoke OAuth apps. ## Related articles * [How to create and manage API keys](https://support.affinity.co/s/article/How-to-create-and-manage-API-keys.md) * [Manage Apps reference](https://support.affinity.co/s/article/Manage-apps-reference.md) * [How to audit API keys in your instance](https://support.affinity.co/s/article/How-to-audit-API-keys-in-your-instance.md) * [Affinity MCP security](https://support.affinity.co/s/article/Affinity-MCP-security.md) * [OAuth Apps and MCP Clients (developer guide)](https://developer.affinity.co/pages/external-api-v2/oauth-apps) ## Related topics - [Manage Apps Reference](https://support.affinity.co/s/article/Manage-apps-reference.md) - [Connect AI Tools to Affinity with MCP](https://support.affinity.co/s/article/Tutorial-MCP-connect-ai-tools-to-affinity.md) - [Affinity MCP Reference](https://support.affinity.co/s/article/Affinity-MCP-reference.md) - [How to Explore Your API Usage](https://support.affinity.co/s/article/How-to-explore-API-usage.md) - [Troubleshooting Affinity MCP](https://support.affinity.co/s/article/Troubleshooting-Affinity-MCP.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.