Authentication & API keys

Requests to the JOGL Network API are authenticated one of two ways: a personal API key (for REST, and for MCP clients that are not connected over OAuth), or a short-lived OAuth access token issued through the WorkOS AuthKit connector (the one-click MCP connector path, see MCP server). Keys are minted by you, for you, and inherit your rights at the time each call is made.

Minting a key

Go to Settings → API/MCP in the app and create a key. A key belongs to your personal billing owner and carries exactly your own rights, which are not the same for reading and writing:

Reading — every non-archived community you belong to, in any role, plus any non-archived community owned by an organization you manage. Ordinary membership is enough; you do not have to be an admin. Archiving a community takes it out of the key's reach even though your membership row survives, so a read against it returns 403 and scope: "all" simply omits it.
Writing — only where you are an admin or owner of the community, directly or through an organization that owns it. See Enabling write access below.

You can optionally attach a community allowlist that narrows a key to a subset of that set — an allowlist can only narrow, never expand.

Keys are always personal. Organization-owned keys can no longer be created; a legacy org-owned key that already exists keeps working until you revoke it, but it never inherits its minter's personal community-admin rights (it acts on ownership only).

The full secret is shown once, at creation, and is never recoverable afterwards. Store it somewhere safe. Only a hash and a display prefix (e.g. jogl_live_AbCd1234) are kept. Revoke a leaked key in Settings; revocation takes effect on the next request.

Keys are prefixed jogl_live_ (live) or jogl_test_ (test). The prefix is a label, not a boundary — a jogl_test_ key reads and writes the same data as a live one on the deployment that minted it. See the warning on the API keys page.

Presenting a key

Send the key on every request as either header:

Authorization: Bearer jogl_live_…

X-API-Key: jogl_live_…

Scopes

Scopes are chosen at mint time. They come in two tiers.

Read tier — mintable by any signed-in user, no attestation:

Scope	Grants
`search:read`	Expert search
`profile:read`	Read your own / a community member's profile
`enrich:read`	Poll enrichment run status

Write tier — requires an owner attestation (see below):

Scope	Grants
`member:write`	Add people to a community you control, and community-scoped erasure
`enrich:write`	Start enrichment on members of a community you control

self:enrich (enrich your own profile, target-locked) is also mintable by any signed-in user with no attestation, but because it starts a billable side effect it is not part of the one-click Read preset in the create-key UI — select it explicitly under Advanced. A plain "Read" key can't call POST /v1/me/enrich.

Enabling write access (attestation)

Carrying a *:write scope is not enough. Writes are gated at use time by two independent checks:

Ownership or community-admin — your billing owner must be the target community's billing owner, or — for a personal (user-owned) key only — your owner must be an admin of the community. A legacy organization-owned key never gets that second path (see above): it acts on ownership alone, so it still gets 403 for a community its organization does not own, even when the person who minted it administers that community. The delegated-admin path applies to all three community writes — adding members (member:write), starting enrichment (enrich:write), and member erasure — once the community's billing owner has enabled writes.
Write attestation — the community's billing owner must have explicitly enabled API writes, recorded as a versioned, auditable attestation.

You enable this in Settings → API/MCP → Write access. Until then, write calls return 422 unprocessable. When the just-in-time consent feature is switched on for your account, the same situation returns 422 owner_consent_required and queues a consent request the owner can approve from the write-consent queue in Settings; retrying the same call after approval then succeeds.

Rate limits

Each key has a per-minute token bucket. The tier is decided when the key is minted and stored on the key, so upgrading your plan later does not change an existing key — mint a new one.

Restricted (free) tier — 2 requests/min, burst 5, and a hard 20/day cap. This is the default for an owner who is not privileged.
Standard tier — the requested rate (default 60/min), full burst, and no daily cap. You are privileged when any of these holds at mint time: your billing owner is an organization; your owner has an active paid plan (a free trial does not count); you are the owner or admin of at least one community; or you are an owner or admin of an organization that owns at least one community, which carries the same tier your retired org-owned key used to get.

Don't hardcode a rate — read the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers on every authenticated response and pace off RateLimit-Remaining. Exceeding the limit returns 429 with a Retry-After header.

OAuth (one-click connectors)

Instead of a static key, an MCP client can connect via OAuth (WorkOS AuthKit). The bearer token is then a short-lived JWT rather than a jogl_* key. Authorization is always re-checked against live key state, so revoking a grant takes effect immediately. See MCP server.