---
name: clari-install-auth
description: >-
  Configure a least-privilege Clari identity and validate Revenue API or Copilot credentials without exposing secrets. Use when starting an integration or rotating access. Trigger with: "set up Clari auth", "configure a Clari token", "test Copilot credentials".
allowed-tools: Read, Grep, Write, Edit
version: 2.0.0
argument-hint: '[surface-revenue-or-copilot-and-environment]'
model: inherit
effort: high
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
  - saas
  - clari
  - authentication
  - tokens
  - integration-user
compatibility: 'Requires an entitled Clari tenant, an approved integration owner, and access to the relevant Revenue API or conversation-intelligence workspace settings.'
title: clari-install-auth
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/clari-install-auth
last_updated: 2026-10-07T06:06:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/official-docs.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/clari-install-auth/references/official-docs.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/clari-install-auth`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/clari-install-auth`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/clari-install-auth) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/clari-install-auth`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/clari-install-auth --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/clari-install-auth --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Clari Integration Identity and Token Setup

## Overview

Establish a dedicated integration identity before building any data flow. Treat Revenue API tokens, ingestion partner keys, and Copilot key/password pairs as separate credentials with separate rotation and revocation paths.

## Prerequisites

- Named business owner and technical owner for the integration
- Target surface: Revenue API, v2 ingestion, or Copilot API
- Approved secret manager and a non-production validation boundary

## Instructions

### Step 1: Choose the surface

Record the exact base URL and authentication contract: Revenue API uses the `apikey` header, v2 ingestion additionally requires `partnerkey`, and Copilot uses both `X-Api-Key` and `X-Api-Password`.

### Step 2: Create a dedicated identity

Use a service or integration user whose hierarchy and forecast access match the intended export scope. Do not reuse a personal administrator credential.

### Step 3: Issue and escrow credentials

Generate the credential in the Clari settings exposed for the entitled product, capture it once into the approved secret manager, and record owner and rotation metadata without copying the value into tickets or logs.

### Step 4: Validate the smallest read

For Revenue API, call the administrative limits read or another entitled read-only endpoint. For Copilot, list a narrowly scoped resource such as users; do not create or update CRM records during authentication testing.

### Step 5: Prove effective access

Confirm the identity can see only the expected organization, forecast hierarchy, workspace, and object set. Treat an empty result separately from successful authorization.

### Step 6: Document rotation and revocation

Define overlap, rollback, dependent-job restart, and emergency revocation procedures before production use.

## Authentication

Send credentials only in the provider-documented headers over HTTPS. Redact all token and password values, never persist them in shell history or fixtures, and remember that revoking a Revenue API token or deactivating its owning user can break active integrations.

## Tool Discipline

Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.

## Output

- Credential inventory containing references, owners, scopes, and rotation dates
- Redacted read-only validation receipt with endpoint, timestamp, and status
- Revocation and dependent-job recovery plan

Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.

## Examples

A forecast warehouse integration receives a dedicated user and token limited by the user’s Clari hierarchy. The operator validates `/admin/limits`, records only the HTTP status and organization context, and schedules a rotation drill before enabling exports.

## Error Handling

| Failure | Response |
| --- | --- |
| 401 or authentication failure | Verify the correct header contract and secret reference; rotate rather than printing the credential. |
| 403 or missing data | Check product entitlement, hierarchy opt-in, forecast access, partner enablement, and workspace scope. |
| Credential owner is deactivated | Issue a replacement under an approved integration identity and restart dependents only after read-only validation. |

## Resources

- [First-party source notes](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/clari-install-auth/references/official-docs.md)
- [Clari Revenue API reference](https://developer.clari.com/default/documentation/external_spec)
- [Clari Copilot API reference](https://api-doc.copilot.clari.com/)
