> ## 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. **How-to** — task-oriented recipe. **Last Updated:** October 2, 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, or an in-house assistant built on the Affinity MCP server. **Use an [API key](/s/article/How-to-create-and-manage-API-keys)** 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. * Decide which **scopes** the tool needs. Give it the fewest that work. ## Part 1: Create an OAuth app ### Step 1: Open Manage Apps 1. Click **Settings** in the left navigation. 2. Click **Manage Apps**. 3. Click **New App**, then choose **OAuth App**. If you only see a **New OAuth App** button, click that instead. ### 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. | **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. ### 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. **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. ### 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. ## 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](/s/article/Getting-started-with-Affinity-MCP). | | `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. | `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`. ## 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**. ## 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. ## 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. ## FAQ **Is an OAuth app the same as connecting Claude or ChatGPT to Affinity?** No. Claude, ChatGPT, Notion and the other AI tools listed in **Settings → Affinity MCP** are built-in connections that an admin turns on or off on that page. You create an OAuth app for your own organization's tools. See [Getting started with Affinity MCP](/s/article/Getting-started-with-Affinity-MCP). **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](/s/article/How-to-create-and-manage-API-keys) * [Manage Apps reference](/s/article/Manage-apps-reference) * [How to audit API keys in your instance](/s/article/How-to-audit-API-keys-in-your-instance) * [Affinity MCP security](/s/article/Affinity-MCP-security) ## Related topics - [Manage Apps Reference](/s/article/Manage-apps-reference.md) - [Tutorial 13: Automation and Rules](/s/article/Tutorial-13-automation-and-rules.md) - [Affinity MCP Reference](/s/article/Affinity-MCP-reference.md) - [Connect AI Tools to Affinity with MCP](/s/article/Tutorial-MCP-connect-ai-tools-to-affinity.md) - [Affinity MCP: Security & data handling](/s/article/Affinity-MCP-security.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.