Authentication

Every /v1 request is authenticated. From your own systems, authenticate with a personal access token (PAT) sent as a bearer token:

Authorization: Bearer waafir_pat_…

Issue, restrict and revoke tokens under Add-ons → Connect. The personal access tokens guide covers issuance, expiry (90 days by default, 365 at most), the one-time reveal and revocation. Those rules are the same for the Platform API. This page covers what a token can do once you hold one.

A personal access token acts as the person who issued it, inside that person's organisation. There is no organisation parameter in any URL or body, because the token already pins it.

The three token checks

A token-authenticated request has to clear these three checks, among others. Organisation security policy and the endpoint's own checks can also refuse it (see below). Two of the three have a code of their own. A role refusal can answer FORBIDDEN, which other refusals share, so read the code together with the endpoint's requirements.

Token scopes

A token carries one scope: read, write or admin, in increasing order of authority. A higher scope includes everything below it.

The scope an endpoint needs follows its HTTP method by default:

• GET, HEAD and OPTIONS need read.
• Every other method (POST, PATCH, PUT, DELETE) needs write.

Some endpoints declare a different scope. The usual case is a POST that only runs a query, which needs just read. The endpoints reference shows the scope each endpoint actually requires, so check it there rather than inferring it from the method.

Required role and the role ceiling

Scope says what the token may do. The endpoint's required role says who the person must be. Many /v1 endpoints require the deal team (an organisation owner, admin or member). Changes to the team and to access grants, among others, require an owner or admin. Investors and other guests hold no deal-team role, so deal-team endpoints refuse them. Other endpoints declare no role gate at the authentication layer and check access inside the endpoint instead. For example, the portfolio-monitoring routes check the monitoring add-on and the caller's monitoring access. The endpoints reference shows each endpoint's role gate. Where none is declared, expect the endpoint itself may still refuse.

A token also records its issuer's role at the moment it was issued, as a ceiling. The role Waafir applies is the lower of the issuer's current role and that ceiling. A member who is later promoted to admin still acts as a member through a token issued earlier; issue a new token to use the new role. A person whose role is lowered loses the authority immediately, whatever the token recorded. Either shortfall is refused with 403, as FORBIDDEN or PAT_ROLE_CEILING.

Data-room-restricted tokens

A token issued with specific data rooms selected, rather than All data rooms, reaches only those rooms. A request that names any other data room is refused with PAT_DATAROOM_SCOPE. Some organisation-wide endpoints refuse a restricted token outright, with the same code, because their answer spans data rooms the token cannot see. Use an unrestricted token for those. GET /api/v1/session accepts either kind.

Other refusals you may meet

• 401 UNAUTHORIZED: no Authorization header, or a token that is unknown, expired or revoked.
• 404 for another organisation's resource. An id belonging to another organisation is treated as not found, so it is not confirmed to exist.
• Organisation security policy. If your organisation has an IP allowlist, a request from outside it answers IP_BLOCKED. Two-factor enforcement can answer MFA_SETUP_REQUIRED or MFA_CHALLENGE_REQUIRED.
• 429 RATE_LIMITED. Some endpoints declare a per-minute ceiling for each identity, shown on the endpoint. The rest use the platform default. Back off and retry.

The error codes page lists the known codes with their meanings.