The Pirros External API lets third-party tools — data warehouses, dashboards, custom integrations, Revit-side tooling — read and write your firm's Pirros data on your behalf. As a firm admin, you create the credentials your integration vendor will use, decide what data they can touch, and hand the credentials off. This article walks through that setup end-to-end.

If you're the developer who'll actually be calling the API, read the Pirros External API: developer guide instead.

Before you start

You'll need:

A firm-admin account with the Manage API keys permission. If you don't see API Keys under Settings, either you don't have this permission (ask another firm admin to grant it).
A short conversation with whoever's building the integration about:
Which workspace(s) they need access to.
What they need to do — read families and details? Create stashes? Download RFA / PDF / RVT files?
A secure way to send credentials (1Password, a shared vault, an encrypted message — not email or Teams).

Step 1 — Open API Keys settings

In the Pirros web app, go to Settings → API Keys.

You'll see a list of any keys your firm already has. To create a new one, click Create new API Key.

Step 2 — Create the key

The creation flow asks you for:

1. A name. Use something descriptive — the name is how you and other admins will recognize this key later. Examples: Acme Data Warehouse — Production, Hubble Dashboard — Staging, Revit Pricing Add-in. Avoid generic names like "API key 1." (Note: the name is set at creation and can't be changed later — see "Managing existing keys" below.)

2. The scope grants. Each grant is a workspace + filter + action triple — the workspace scopes the grant to one workspace in your firm, the filter says which entities the integration can touch, and the action says what it can do with them. A single key can hold grants across multiple workspaces in your firm, but most integrations only need one.

Pirros ships with system filters in every workspace that cover broad access. They appear with their literal stored names:

Filter (name shown in the UI)	Means
default:families	Every family in the workspace
default:details	Every detail in the workspace
default:stashes	Every stash in the workspace
default:tags	Every tag in the workspace

There is also one firm-global system filter, default:any ("Full access"), which grants access to every entity type across the firm; it appears once in the list labeled (firm-global).

Pair each filter with one or more actions:

Action	Lets the integration
Read	Fetch metadata (e.g. GET /families/{id}, GET /details)
Write	Create or update (e.g. POST /stashes, PATCH /stashes/{id})
Download	Get a download URL for a detail's RVT/PDF or a family's RFA

Grant only the actions the integration actually needs. A read-only data warehouse, for example, only needs read access — not write or download. Note: tag filters support only Read and Write — there is no download action for tags.

If you need access narrower than "every family in workspace" — for example, only details from one library project, or only stashes a specific user created — you can author a custom filter first and then assign it here. See Resource filters: controlling what your API integrations can access.

Click Create when you're done.

Step 3 — Save the credentials

After you create the key, Pirros shows you two values:

Client ID — the public identifier for this key. You can see this again later in the API Keys list.
Client Secret — the password. Copy it now and store it in a password manager. (For convenience the dialog also offers Download as .env file, which writes PIRROS_CLIENT_ID and PIRROS_CLIENT_SECRET.)

ℹ️ You are not locked out if you miss it. Unlike a GitHub-style token, a Pirros client secret can be retrieved again later — see "Managing existing keys" below. Still, copy it into your password manager now so you don't have to.

Step 4 — Hand off to your integrator

Send the integrator:

The Client ID
The Client Secret (or the downloaded .env file)
The workspace UUID(s) they have access to

Use a secure channel — a shared password-manager vault is the cleanest option.

The integrator doesn't need anything else from you to start making API calls.

Managing existing keys

From Settings → API Keys, open a key (the kebab menu offers View, Regenerate, Revoke). You can:

Reveal the secret — from the key's detail page, Reveal secret shows the original client secret again. Each reveal is audit-logged. Use this when a vendor lost their copy.
Regenerate the secret — Regenerate rotates to a brand-new secret in place. This immediately invalidates the old secret and any tokens minted from it. Use this if a secret may be compromised.
Revoke a key — this is instant. The next API call the integration makes with this key fails with HTTP 401 and the error code invalid_token. Use this when an employee with key access leaves, if a key is leaked, or when you're decommissioning an integration.
See the last-used timestamp — handy for finding keys that nobody's using anymore.

A key's name can't be changed after creation. If you need a different name, revoke the key and create a new one.

If a vendor loses their secret, you do not have to delete and recreate the key — use Reveal secret to retrieve it, or Regenerate to issue a fresh one.

Best practices

One key per integration. Don't share keys between vendors — when one needs to be revoked, the others keep working.
Descriptive names. Future-you needs to know who's using what.
Minimum scope. A vendor that only reads data shouldn't have write or download grants. You can always add more later.
Rotate periodically (use Regenerate), or immediately if anyone with key access leaves your firm.
Audit regularly. A quarterly look at the keys list — what's still in use (last-used timestamp), what's gone stale — catches keys that should have been revoked months ago.