Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Nooks (API Key)

Scalekit connector
Open markdown

The Nooks (API Key) connector lets your AI agent act in each user's Nooks (API Key) account. Each user connects their own Nooks (API Key) access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 20 tools.

Tools
20
What they doRead · write · destructive
16 · 4 · 016 read4 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Nooks (API Key) connection

    In AgentKit > Connections, create a Nooks (API Key) connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    Each user connects with a Nooks API key. Scalekit stores the key on the user’s connected account and sends it as a Bearer token with every tool call.

    1. Create a Nooks API key

      • Sign in to Nooks and open Developer Settings → API Keys.
      • Create a key and copy it. Nooks API keys start with nooks-api-.

    2. Create a connection in Scalekit

      • In Scalekit dashboard, go to AgentKit → Connections → Create Connection. Find Nooks (API Key) and click Create.
      • Note the Connection name — you will use this as connection_name in your code (e.g., nooksapikey).
      • Click Save.

    3. Add a connected account

      Connected accounts link a specific user identifier in your system to a Nooks API key. Add one in the dashboard to test. In production, each user adds their own through the authorization link: they enter their credentials on the page it opens.

      In the dashboard, to test

      • Open the connection you created and click the Connected Accounts tab → Add account.
      • Fill in:
        • Your User’s ID — a unique identifier for this user in your system (e.g., user_123)
        • API Key — the Nooks API key from step 1
      • Click Create Account.

      From your backend, if your app already has the credentials

      For example, when users enter them on a settings page in your app:

      import { Scalekit, ConnectorStatus } from '@scalekit-sdk/node';
      

      const scalekit = new Scalekit(
        process.env.SCALEKIT_ENVIRONMENT_URL,
        process.env.SCALEKIT_CLIENT_ID,
        process.env.SCALEKIT_CLIENT_SECRET,
      );
      

      // Never hard-code credentials — read from secure storage or user input
      const nooksApiKey = getUserNooksApiKey(); // retrieve from your secure store
      

      const authorizationDetails = {
        details: {
          case: 'staticAuth',
          value: { details: { token: nooksApiKey } },
        },
      };
      

      let { connectedAccount } = await scalekit.actions.upsertConnectedAccount({
        connectionName: 'nooksapikey',
        identifier: 'user_123',
        authorizationDetails,
      });
      

      // Make sure the account is ACTIVE before the first tool call.
      if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
        ({ connectedAccount } = await scalekit.actions.upsertConnectedAccount({
          connectionName: 'nooksapikey',
          identifier: 'user_123',
          authorizationDetails,
        }));
      }

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'nooksapikey'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Nooks (API Key):', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'nooksapikey_accounts_list',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Nooks (API Key) credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • nooksapikey_account_getGet one Nooks account (company) by its ID.Read-only

    Get Account

    Get one Nooks account (company) by its ID. Returns the account's name, domain, CRM IDs, owner, and optionally its CRM custom fields. Use nooksapikey_account_get when you have the ID. Use nooksapikey_accounts_list to search by name, domain, or CRM ID.

    Inputs

    idstringrequired
    Nooks ID (UUID) of the account. Get it from nooksapikey_accounts_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    include_crm_custom_fieldsboolean
    Set to true to add each record's CRM custom fields as crmCustomFields, keyed by CRM field name (for example {"hs_lead_status": "OPEN"}).
  • nooksapikey_accounts_listList CRM-sourced accounts (companies) in Nooks, filtered by IDs, exact name, domain, CRM ID, or update time.Read-only

    List Accounts

    List CRM-sourced accounts (companies) in Nooks, filtered by IDs, exact name, domain, CRM ID, or update time. Returns up to 100 accounts per page with name, domain, CRM IDs, and owner, plus a links.next cursor. Use nooksapikey_accounts_list to find an account. Use nooksapikey_account_get when you already have the account ID.

    Inputs

    filter_crm_idstring
    Only return the account with this ID in your CRM. Example: 0015g00000XyZabAAB.
    filter_domainstring
    Only return the account with this exact domain. Example: acme.com.
    filter_idsstring
    Only return accounts with these Nooks IDs, comma-separated. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    filter_namestring
    Only return the account with this exact name. Example: Acme Inc.
    include_crm_custom_fieldsboolean
    Set to true to add each record's CRM custom fields as crmCustomFields, keyed by CRM field name (for example {"hs_lead_status": "OPEN"}).
    page_afterstring
    Cursor for the next page. Pass the page[after] value from the links.next URL of the previous response, unchanged. Leave empty for the first page.
    page_sizeinteger
    Number of accounts to return per page (1 to 100). Defaults to 50.
    updated_afterstring
    Only return accounts updated at or after this time. Use an ISO 8601 date-time, for example 2024-01-01T00:00:00Z.
    updated_beforestring
    Only return accounts updated before this time. Use an ISO 8601 date-time, for example 2024-12-31T23:59:59Z.
  • nooksapikey_call_dispositions_listList the call dispositions (call outcomes) configured in the Nooks workspace.Read-only

    List Call Dispositions

    List the call dispositions (call outcomes) configured in the Nooks workspace. Returns up to 100 dispositions per page with id and name, plus a links.next cursor. Use nooksapikey_call_dispositions_list to get disposition IDs for filtering nooksapikey_calls_list.

    Inputs

    filter_namestring
    Only return the disposition with this exact name. Example: Meeting Booked.
    page_afterstring
    Cursor for the next page. Pass the page[after] value from the links.next URL of the previous response, unchanged. Leave empty for the first page.
    page_sizeinteger
    Number of dispositions to return per page (1 to 100). Defaults to 50.
  • nooksapikey_call_getGet one Nooks call by its ID.Read-only

    Get Call

    Get one Nooks call by its ID. Returns the call's time, duration, direction, disposition, notes, prospect, and owner, optionally with those related records embedded. Use nooksapikey_call_get when you have the call ID. Use nooksapikey_calls_list to find calls.

    Inputs

    idstringrequired
    Nooks ID (UUID) of the call. Get it from nooksapikey_calls_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    includestring
    Related records to embed in the response instead of returning only their IDs (max 3). Pass one or more of these values, comma-separated: prospect, sequence, sequenceStep, callDisposition, owner. Example: prospect,sequence.
  • nooksapikey_calls_listList calls made in Nooks, filtered by call time, ingestion time, prospect, account, disposition, or caller.Read-only

    List Calls

    List calls made in Nooks, filtered by call time, ingestion time, prospect, account, disposition, or caller. Returns up to 100 calls per page with time, duration, direction, disposition, prospect, and owner, plus a links.next cursor. Use nooksapikey_calls_list to find calls. Use nooksapikey_call_get for one call by ID.

    Inputs

    account_idstring
    Only return calls linked to this account. Use the account's Nooks ID (UUID) from nooksapikey_accounts_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    created_afterstring
    Only return calls ingested into Nooks at or after this time. Use an ISO 8601 date-time, for example 2024-01-01T00:00:00Z.
    created_beforestring
    Only return calls ingested into Nooks at or before this time. Use an ISO 8601 date-time, for example 2024-12-31T23:59:59Z.
    disposition_idstring
    Only return calls logged with this disposition. Use the disposition's Nooks ID (UUID) from nooksapikey_call_dispositions_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    filter_idsstring
    Only return calls with these Nooks IDs, comma-separated. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    includestring
    Related records to embed in the response instead of returning only their IDs (max 3). Pass one or more of these values, comma-separated: prospect, sequence, sequenceStep, callDisposition, owner. Example: prospect,sequence.
    owner_idstring
    Only return calls placed by this user. Use the user's Nooks ID from nooksapikey_users_list or nooksapikey_me_get. Example: Xk3pQ9rT2vLmN8sA1bC4dE5fG6h7.
    page_afterstring
    Cursor for the next page. Pass the page[after] value from the links.next URL of the previous response, unchanged. Leave empty for the first page.
    page_sizeinteger
    Number of calls to return per page (1 to 100). Defaults to 50.
    prospect_idstring
    Only return calls with this prospect. Use the prospect's Nooks ID (UUID) from nooksapikey_prospects_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    time_afterstring
    Only return calls that happened at or after this time. Use an ISO 8601 date-time, for example 2024-01-01T00:00:00Z.
    time_beforestring
    Only return calls that happened at or before this time. Use an ISO 8601 date-time, for example 2024-12-31T23:59:59Z.
    updated_afterstring
    Only return calls updated at or after this time. Use an ISO 8601 date-time, for example 2024-01-01T00:00:00Z.
    updated_beforestring
    Only return calls updated before this time. Use an ISO 8601 date-time, for example 2024-12-31T23:59:59Z.
  • nooksapikey_email_getGet one Nooks email by its ID, including unsent drafts and queued sends.Read-only

    Get Email

    Get one Nooks email by its ID, including unsent drafts and queued sends. Returns the email's subject, body, status, recipients, and related prospect, task, and sequence. Use nooksapikey_email_get when you have the email ID. Use nooksapikey_emails_list to find sent emails.

    Inputs

    idstringrequired
    Nooks ID (UUID) of the email. Get it from nooksapikey_emails_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    includestring
    Related records to embed in the response instead of returning only their IDs (max 3). Pass one or more of these values, comma-separated: prospect, task, sequence, sequenceStep. Example: prospect,task.
  • nooksapikey_emails_listList sent and in-flight emails in Nooks, filtered by IDs, prospect, task, account, status, or update time.Read-only

    List Emails

    List sent and in-flight emails in Nooks, filtered by IDs, prospect, task, account, status, or update time. Returns up to 100 emails per page with subject, status, recipients, and related prospect and sequence, plus a links.next cursor. Unsent drafts are not listed. Use nooksapikey_emails_list to review outreach. Use nooksapikey_email_get for one email, including drafts.

    Inputs

    account_idstring
    Only return emails to prospects at this account. Use the account's Nooks ID (UUID) from nooksapikey_accounts_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    filter_idsstring
    Only return emails with these Nooks IDs, comma-separated. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    includestring
    Related records to embed in the response instead of returning only their IDs (max 3). Pass one or more of these values, comma-separated: prospect, task, sequence, sequenceStep. Example: prospect,task.
    page_afterstring
    Cursor for the next page. Pass the page[after] value from the links.next URL of the previous response, unchanged. Leave empty for the first page.
    page_sizeinteger
    Number of emails to return per page (1 to 100). Defaults to 50.
    prospect_idstring
    Only return emails to this prospect. Use the prospect's Nooks ID (UUID) from nooksapikey_prospects_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    statusstring
    Only return emails with these delivery statuses. Pass one or more of these values, comma-separated: draft, in_progress, sent, failed. Example: sent.
    task_idstring
    Only return emails sent for this sequence task. Use the task's Nooks ID (UUID) from nooksapikey_tasks_list. Example: 3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f.
    updated_afterstring
    Only return emails updated at or after this time. Use an ISO 8601 date-time, for example 2024-01-01T00:00:00Z.
    updated_beforestring
    Only return emails updated before this time. Use an ISO 8601 date-time, for example 2024-12-31T23:59:59Z.
  • nooksapikey_me_getGet the Nooks workspace and user behind the current credential.Read-only

    Get Current User

    Get the Nooks workspace and user behind the current credential. Returns workspaceId, userId, email, name, and, for OAuth tokens, the client ID and granted scopes. Use nooksapikey_me_get to check the connection and to get your own user ID for owner fields.

    Inputs

    This tool takes no inputs.

Workflows

List today’s open call tasks
const tasks = await actions.executeTool({
  connector: 'nooksapikey',
  identifier: 'user_123',
  toolName: 'nooksapikey_tasks_list',
  toolInput: {
    action: 'call',
    status: 'ready',
    due_before: '2024-06-01T23:59:59Z',
    include: 'prospect',
  },
});
console.log(tasks);
Enroll a prospect in a sequence

Find the prospect with nooksapikey_prospects_list (for example by filter_emails), the sequence with nooksapikey_sequences_list, and your user ID with nooksapikey_me_get.

const enrollment = await actions.executeTool({
  connector: 'nooksapikey',
  identifier: 'user_123',
  toolName: 'nooksapikey_sequence_state_create',
  toolInput: {
    prospect_id: '3f2b8c1e-4d5a-4b6c-9e7f-1a2b3c4d5e6f',
    sequence_id: '9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d',
    owner_id: 'Xk3pQ9rT2vLmN8sA1bC4dE5fG6h7',
  },
});
console.log(enrollment);
Page through results

List tools return up to 100 records per page. When links.next is present in the response, pass its page[after] value as page_after to get the next page.

const nextPage = await actions.executeTool({
  connector: 'nooksapikey',
  identifier: 'user_123',
  toolName: 'nooksapikey_calls_list',
  toolInput: { page_size: 100, page_after: 'eyJpZCI6IjNmMmI4YzFlIn0' },
});
All 64 in CRM & Sales