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 keys in the app and create a key. A key belongs to your personal billing owner and can act across every community you own or administer (including communities owned by an organization you manage). You can optionally attach a community allowlist that narrows a key to a subset of those communities — an allowlist can only narrow, never expand.

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).

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
`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 user-owned key) your owner must be an admin of the community. This 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. (An org-owned key never inherits its minter's personal admin rights — it uses ownership only.)
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 keys → Write access. Until then, write calls return 422.

Rate limits

Each key has a per-minute token bucket, and the tier depends on the key owner:

Restricted (free) tier — the default for a key whose owner is not privileged (an individual with no org and no paid standing): 2 requests/min, burst 5, and a hard 20/day cap.
Standard tier — a privileged owner (an organization, or an owner with paid standing) gets the requested rate (default 60/min), full burst, and no daily cap.

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.