sign in →

docs / authentication

Authentication

Bearer keys per project, with two scopes. Share tokens for public read-only views.

docs/authenticationapi v1

API keys#

Send the key as a bearer token on every request:

curl https://api.nolvin.com/v1/domains -H "Authorization: Bearer nlv_…"

A key belongs to exactly one project and sees all of that project's domains. Only a SHA-256 hash is stored, so the plaintext is shown once — at creation or rotation. An unknown or revoked key gets 401 {"error":"invalid API key"}; a key of an archived project gets 403.

Scopes#

ScopeCan
readEvery GET: domains, pages, graph queries, events, webhooks and share listings. Also send feedback.
fullEverything a read key can, plus creating and changing domains, sources, gates, crawls, curation, webhooks and share links — and owner actions: keys, members, invites and deletes.

A write call with a read key returns 403 {"error":"read-only access"}. Give dashboards and public-facing services read keys; keep full keys server-side.

A full-scope key can manage keys and members and delete the project. Treat it like an owner password.

Managing keys#

# create (owner or full key)
curl https://api.nolvin.com/v1/project/keys -H "Authorization: Bearer $NOLVIN_KEY" -H "Content-Type: application/json" \
  -d '{"name": "dashboard", "scope": "read"}'
{"id": "…", "key": "nlv_…", "scope": "read"}

# rotate: new secret, old one stops working immediately
curl -X POST https://api.nolvin.com/v1/project/keys/$KEY_ID/rotate -H "Authorization: Bearer $NOLVIN_KEY"

# revoke
curl -X DELETE https://api.nolvin.com/v1/project/keys/$KEY_ID -H "Authorization: Bearer $NOLVIN_KEY"

GET /v1/project/keys lists keys with last_used_at, which helps find stale ones.

Members and roles#

People sign in to the console with a session; their role in the project decides what they can do:

RoleAccess
ownerEverything, including keys, members, invites and deletes.
editorBuild and change graphs; no key, member or delete management.
viewerRead-only, like a read key.

Owners invite people with POST /v1/project/invites, which returns an accept link.

Share tokens#

A share link publishes read-only views of one domain — any of graph, timeline, map, search — behind an unguessable shr_ token. No key is needed to read them, so they suit public embeds.

curl https://api.nolvin.com/v1/domains/$DOMAIN/share -H "Authorization: Bearer $NOLVIN_KEY" -H "Content-Type: application/json" \
  -d '{"views": ["timeline", "map"]}'
{"id": "…", "token": "shr_…", "views": ["timeline","map"], "public_base": "/v1/public/shr_…"}

curl https://api.nolvin.com/v1/public/shr_…/timeline

Revoke with DELETE …/share/{id}. Public views omit relationships and provenance.