Authentication

Calls to /api/v1/x send Authorization: Bearer with a Capsure token. The token carries the user and the firm. You do not pass the firm again.

These routes stay on /api/v1/auth. They are not under /api/v1/x.

Method	Path	What it does
POST	/api/v1/auth/session	Exchange an Entra or Google id token for a Capsure token
GET	/api/v1/auth/me	The user, the firm, and the memberships on this token
GET	/api/v1/auth/tenants	Firms this email can open
POST	/api/v1/auth/switch-tenant	A new token for a firm this email already belongs to

The session body can name tenantId when the email belongs to more than one firm. After that, the choice is inside the token. switch-tenant checks membership and returns a new token. It cannot open a firm the email is not in.

Creating a firm is not part of this API.

A missing or rejected token is 401. The body may be empty. See Errors.

A tenantId on any /api/v1/x query or body is 400. The message says the firm comes from the token.

API tokens

A session lasts about 12 hours. For a script that should keep calling, issue an API token in Administration → API tokens. It acts as you, for the firm you are in, until the date you set or until you revoke it.

The secret is shown once. Send it the same way: Authorization: Bearer and the value that starts with cap_.

You choose scopes when you issue it, and you can add a short description of what the token is for. A write scope includes the matching read. A call still needs your role. A scope cannot add a permission you do not have. Catalog and OpenAPI need no extra scope.

Scope	What it allows
records:read, records:write	Records, search, changes, strategies, deal sources, dashboards, report templates, the workspace, and the product screens
fields:read, fields:write	Custom field definitions and attribute sets
views:read, views:write	Saved views
automations:read, automations:draft, automations:publish	Read, save a draft, publish
forms:read, forms:draft, forms:publish	Read, save a version, activate or deactivate
agents:read, agents:draft	List profiles, or create, update, and archive one
quick-actions:read, quick-actions:write	List quick actions, or change them
processes:read, processes:write	List processes, or create and update one
connectors:read, connectors:draft, connectors:activate	Read, save and test, or publish, activate, deactivate, and delete
imports:read, imports:draft, imports:apply	Read, create and dry-run, or apply
finance:read, finance:write	Read funds, commitments, and portfolio value. Write creates a fund or a commitment
portfolio:read	List and open portfolio companies

A missing scope is 403 scope_denied. The token can call /api/v1/x and GET /api/v1/auth/me. Other routes return 403 token_route. It cannot issue another token, and it cannot switch firm.

An API token is limited to 300 calls a minute. Over that, the call is 429 rate_limited and Retry-After says how many seconds to wait. A session sign-in is not counted.

On a POST, Idempotency-Key stores the response for 24 hours. The key is reserved before the write. Send the same key and the same body again to receive that response, including Idempotent-Replayed: true. A different body, or the same key on a different route, is 409 idempotency_conflict. A second call while the first is still running is 409 idempotency_in_progress. After 24 hours the key can be reused. The key belongs to the firm and the person, not to one token. A key is 1 to 255 characters with no spaces.

The stored match is the method, the path, the query, and the body. If-Match is not part of that match.

A rejected request, other than 412 version_conflict, is stored and replayed. The same key returns that rejection and does not run the write again. A 412 is not stored, so the same key and the same body can be sent again with a new If-Match, and that call runs. A server failure, a 5xx, deletes the reservation. The same key can be sent again, and that call runs. If the first call already finished and stored a success, a later call with the same key replays that success even when If-Match is different.