This guide walks you through creating an OAuth application in Nooks, configuring its scopes and redirect URI, and using it to authenticate users on your end via the standard OAuth 2.0 authorization-code flow.

Background

OAuth lets your application access Nooks data on behalf of a user without that user ever sharing their password or a long-lived API key. Each user that connects to your app grants a specific set of permissions (scopes), and your app receives short-lived access tokens it can use to call the Nooks API.

Use an OAuth app instead of an API key when:

• You are building an integration that will be installed by multiple Nooks workspaces or users.

• You want users to grant — and revoke — access themselves.

• You need scoped permissions rather than full account access.

For background on the Nooks public API, see the Nooks API documentation. If you only need to script against your own account, see How to Generate a Nooks API Key instead.

Creating a New OAuth App

This section will walk through creating a new OAuth App in Nooks. You will need to be a Nooks admin to follow these steps.

Step 1: Navigate to the OAuth Apps Tab

First, head to the OAuth Apps tab in the Developer page.

1. Open Nooks and go to Settings.

2. In the left sidebar, select Developers > OAuth Apps.

3. You'll see a list of any existing OAuth apps in your workspace.

Note: If you do not see this tab, please contact Nooks support.

The table on this page contains the following columns.

Step 2: Create a New OAuth App

1. Click + New OAuth App in the top right.

2. Fill in the form:

   1. App Name – Shown to users on the consent screen. Keep it short and recognizable (e.g., "Acme CRM Sync").

   2. App Description (optional) – One-line summary of what your app does. Also shown on the consent screen.

3. Click Create.

Step 3: Copy Your Client Credentials

Once created, you'll see your Client ID and Client Secret.

• Client ID is public –it appears in authorization URLs and can be safely embedded in your frontend.

• Client Secret is private — it must only be used from your backend when exchanging codes for tokens or refreshing tokens. Never embed it in client-side code.

Step 4: Fill in the App Details

You should now see the full form to edit your application. Ensure that these fields are filled in.

First, in the App Info tab:

• Logo URL (optional) — A square image (PNG/SVG) shown on the consent screen.

• Privacy Policy URL (optional) – Shown on the consent screen when users authorize your app. Must be in https:// format.

• Terms of Service URL (optional) – Shown on the consent screen when users authorize your app. Must be in https:// format.

Next, in the Auth tab:

• Redirect URI(s) — One or more URLs that Nooks will redirect users back to after they authorize your app. Production redirect URIs must use HTTPS. You can add multiple URIs (e.g. one for production, one for local development like http://localhost:3000/oauth/callback).

Scopes

Scopes define which Nooks API endpoints your app is allowed to call on behalf of a user. Only request the scopes your app actually needs — users will see every scope you request on the consent screen, and over-requesting reduces install conversion.

Common scopes include:

You can select which scopes to request within the app's Auth tab.

The access tokens your app receives will reflect the scopes the user consented to. Calls to endpoints outside those scopes will return a 403 Forbidden.

The OAuth 2.0 Flow

Nooks uses the standard OAuth 2.0 authorization-code flow with PKCE. PKCE (Proof Key for Code Exchange) is required for all clients, including confidential server-side apps. It prevents an attacker who intercepts your authorization code from being able to redeem it.

Step 1: Generate a PKCE Code Verifier and Challenge

Before redirecting the user to the Nooks authentication page, generate a one-time PKCE pair for this auth attempt and store the verifier in the user's session:

• code_verifier — A cryptographically random string, 43–128 characters long, using [A-Z] [a-z] [0-9] - . _ ~.

• code_challenge — The base64url-encoded SHA-256 hash of the verifier (no padding).

Example (Node.js):

import crypto from "node:crypto";

const codeVerifier = crypto.randomBytes(32).toString("base64url");
const codeChallenge = crypto
  .createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

Store codeVerifier server-side (keyed by session or state) — you'll need it in Step 4.

Step 2: Redirect the User to the Authorization URL

Send the user to:

https://app.nooks.ai/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=prospects:read%20sequences:write
  &state=RANDOM_STRING
  &response_type=code
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256

The user will be shown a consent screen listing your app's name, logo, and the scopes you've requested.

Step 3: Handle the Redirect

After the user clicks Allow, Nooks redirects them to your redirect_uri with an authorization code:

https://your-app.com/oauth/callback?code=AUTH_CODE&state=RANDOM_STRING

If the user denies access, you'll receive ?error=access_denied instead. Always verify that the returned state matches the one you generated before continuing, and look up the matching code_verifier you stored in Step 1.

Step 4: Exchange the Code for Tokens

From your backend, exchange the authorization code for an access token and refresh token. Include the original code_verifier — Nooks will hash it and compare against the code_challenge you sent in Step 2.

POST https://app.nooks.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=YOUR_REDIRECT_URI
&code_verifier=YOUR_CODE_VERIFIER

If the code_verifier is missing or doesn't match, the token endpoint returns 400 invalid_grant.

A successful response looks like:

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "prospects:read sequences:write"
}

Authorization codes are single-use and expire within a few minutes — exchange them immediately.

Step 5: Call the Nooks API

Use the access token in the Authorization header on each API request:

Authorization: Bearer <access_token>

Step 6: Refresh the Access Token

Access tokens expire after expires_in seconds (currently 1 hour). When yours is close to expiring, use the refresh token to get a new one:

POST https://app.nooks.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Refresh tokens are long-lived but can be revoked by the user at any time from their Nooks settings. If a refresh call returns 400 invalid_grant, the user has disconnected your app and must re-authorize.

Rotating or Revoking Client Secrets

If a client secret is leaked, rotate it immediately:

1. Go to Settings → Developers → OAuth Apps and open your app.

2. Click Rotate secret.

3. Copy the new secret and deploy it to your backend.

4. The old secret stops working immediately — any in-flight token exchanges using it will fail.

Deleting an OAuth App

Deleting an app immediately invalidates all access and refresh tokens issued under it. Any users who had connected the app will need to re-authorize once you create a new one.

1. Go to Settings → Developers → OAuth Apps.

2. Click the ⋯ menu next to the app and select Delete app.

3. Type the app name to confirm, then click Delete.

You'll see a confirmation: "OAuth app deleted. All issued tokens have been revoked."

Related Resources

• Nooks API Reference

• How to Generate a Nooks API Key

• OAuth 2.0 Authorization Framework (RFC 6749)