Getting Started - Paragon Documentation

This guide walks through everything you need to make your first Agent OS requests: signing a Paragon User Token for your users, sending them a Setup Link to connect their apps, and calling the Context API and Tools API.

Get started with your coding agent

The fastest way to set up Agent OS is with the Paragon Skills in your coding agent (Claude Code, Cursor, Codex, OpenCode, etc.). The skills give your agent the context it needs to set up authentication, create Setup Links, and call the Context and Tools APIs in your codebase. Install them with the npx skills CLI:

npx skills add useparagon/skills

Then ask your agent to set things up, for example:

Starter prompt

Look at my app and set up Paragon Agent OS: sign Paragon User Tokens in my backend, add a way for users to open a Setup Link, and give my agent tools to search context and run Tools with the Context API and Tools API.

To set things up by hand, follow the steps below.

1. Get your Project ID and Signing Key

Open the Overview page in your Paragon dashboard. The SDK Setup Keys section has the 2 values you need, with a tab for each environment:

Project ID: Identifies your project. Every Agent OS request includes it in its path. Click the copy button to copy it.
Signing Key: The private key your backend uses to sign Paragon User Tokens. Click Rotate to generate a new key, and save it right away.

The SDK Setup Keys section of the Paragon dashboard Overview page, showing the Project ID with a copy button and the Signing Key with a Rotate button

Store both in your project’s .env:

.env

PARAGON_PROJECT_ID="your-project-id"
PARAGON_SIGNING_KEY="-----BEGIN PRIVATE KEY-----\n..."

Paragon doesn’t store your Signing Key and can’t show it to you again, so store it somewhere secure. Rotating the key invalidates the previous key for that environment.

Requests are sent to the base URL for your region, for example https://agentos.useparagon.com for US Cloud.

2. Sign a Paragon User Token

Agent OS identifies your users with a Paragon User Token: a JWT that your backend signs for each of your authenticated users. Every Context API and Tools API request is scoped to the Connected User in the token’s sub claim. Sign a JWT with RS256 that includes the sub, aud, iat, and exp claims. Agent OS requires the aud claim to be useparagon.com/<your Project ID>.

server.js

import jwt from "jsonwebtoken";

function getParagonUserToken(user) {
  // JWT NumericDates are in seconds
  const currentTime = Math.floor(Date.now() / 1000);

  return jwt.sign(
    {
      sub: user.id, // Your user's or their company's ID
      aud: `useparagon.com/${process.env.PARAGON_PROJECT_ID}`,
      iat: currentTime,
      exp: currentTime + 60 * 60, // 1 hour from now
    },
    process.env.PARAGON_SIGNING_KEY,
    { algorithm: "RS256" },
  );
}

Send this token as a Bearer token on every Agent OS request:

Authorization: Bearer <Paragon User Token>

Just for testing: Use the Paragon JWT Generator to generate one-off tokens during development. Never use static tokens in production.

If you already use Auth0, Firebase, or a JWKS-compatible authentication server, you can use its tokens instead of signing your own. See Using a managed authentication service.

3. Send your user a Setup Link

A Setup Link is a hosted page where your user connects their apps and chooses what content to sync, so you don’t need to build any connection UI to get started. Call Create Setup Link from your backend with the user’s Paragon User Token. You can also authenticate with a Paragon API key that has the Setup Links API scope by passing the Connected User’s ID as endUserId. This endpoint is served from https://zeus.useparagon.com (US Cloud) or https://zeus.eu.paragon.so (EU Cloud), not the Agent OS base URL.

server.js

const response = await fetch(
  `https://zeus.useparagon.com/projects/${projectId}/setup-links`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${getParagonUserToken(user)}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      expiresIn: 3600, // 1 hour, up to 24 hours
      integrations: ["googledrive", "sharepoint"], // Optional: limit the apps offered
    }),
  },
);

const { url } = await response.json();

Send the returned url to your user, for example by redirecting them to it or opening it in a new tab. On the hosted page, your user:

Connects the apps they want your agent to use. Apps they’ve already connected show a green check.
Chooses what content to sync from their knowledge sources, such as specific folders in Google Drive. Paragon syncs and indexes this content for the Context API.

The Setup Link url contains a signed token. Treat it like a credential and share it only with the intended user.

4. Search your user’s content

Once your user’s content is synced and indexed, your agent can find relevant passages with Search Context:

const response = await fetch(
  `https://agentos.useparagon.com/api/context/projects/${projectId}/search`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${paragonUserToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "q2 roadmap",
      topK: 10,
      identity: "[email protected]", // The account whose access applies
    }),
  },
);

const { results } = await response.json();

Results only include content that identity can access in the source app. Each passage includes a pointer that you can pass to Read Segment Context to read more of the surrounding text.

5. Find and run Tools

The Tools API lets your agent act in your user’s connected apps. Rather than loading every available Tool into your agent, use Search Tools to find the ones relevant to the current task:

const response = await fetch(
  `https://agentos.useparagon.com/api/tools/projects/${projectId}/tools/search`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${paragonUserToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "list open issues",
      connectedOnly: true, // Only Tools for apps your user has connected
      maxSideEffect: "read", // Only Tools that don't change data
    }),
  },
);

const { tools } = await response.json();

Each Tool is returned in a function-calling format that you can pass directly to your LLM. When your model calls a Tool, run it with Run Tool:

const response = await fetch(
  `https://agentos.useparagon.com/api/tools/projects/${projectId}/executions`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${paragonUserToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      intentName: toolCall.name,
      args: toolCall.arguments,
      outputMode: "auto",
    }),
  },
);

const execution = await response.json();

Small results are returned directly on output.inline. Large results are stored and returned as a resultId that your agent can page through with Get Result Rows or Get Result Content, keeping your agent’s context small. See Handling large results.

Tools with a sideEffect other than read have approvalRequired set to true. Use this flag to ask your user to confirm before your agent runs a Tool that writes, deletes, or sends data. See Side Effects.

​Get started with your coding agent

​1. Get your Project ID and Signing Key

​2. Sign a Paragon User Token

​3. Send your user a Setup Link

​4. Search your user’s content

​5. Find and run Tools

​Next steps

Context API

Tools API

Get started with your coding agent

1. Get your Project ID and Signing Key

2. Sign a Paragon User Token

3. Send your user a Setup Link

4. Search your user’s content

5. Find and run Tools

Next steps