Skip to main content
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 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
You can’t change the client type later. If you pick the wrong one, revoke the app and create a new one.
Client Details OAuth Details 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.
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. 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.