Authentication

SynDB uses PASETO v4 tokens for authentication. Access tokens authorize API requests; refresh tokens obtain new access tokens without re-authenticating.

Account Types

Type	How to create	Capabilities
Regular	`POST /v1/user/auth/register` or CLI `syndb user register`	Browse, search datasets
Academic	Verify via CILogon (institutional login)	All regular + SyQL, graph analysis, meta-analysis, upload, jobs
Service	`POST /v1/user/auth/register-service` with `X-Service-Secret` header	Same as Academic (auto-verified)
SuperUser	Promoted by existing superuser	All + federation admin, ontology management

Academic verification is required for compute-intensive operations: query execution, graph analysis, analytics, meta-analysis, and dataset upload.

CLI:

syndb user register
syndb user login

API:

# Register
curl -X POST https://api.syndb.xyz/v1/user/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "...", "display_name": "Jane Doe"}'

# Login — returns access_token and refresh_token
curl -X POST https://api.syndb.xyz/v1/user/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "..."}'

Token Lifecycle

Login returns an access token (15 min TTL) and a refresh token (30 day TTL)
Use the access token in requests: Authorization: Bearer <access_token>

When the access token expires, exchange the refresh token for a new pair:

curl -X POST https://api.syndb.xyz/v1/user/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "..."}'

Each refresh rotates the token — the old refresh token is invalidated

Refresh tokens use family-based rotation: reuse of a revoked token invalidates the entire family, forcing re-authentication.

OAuth Providers

Authenticate through institutional or social identity providers:

Provider	Use case	Scopes
CILogon	Academic institutional login (universities, research labs)	`openid`, `email`, `org.cilogon.userinfo`
GitHub	Social login + ORCID association	`user:email`
Google	Social login	`openid`, `email`, `profile`
GitLab	Social login (supports self-hosted instances)	`read_user`
ORCID	Researcher ID association (requires existing account)	`openid`

All OAuth flows use PKCE (Proof Key for Code Exchange) with SHA-256.

Academic Verification via CILogon

CILogon links your institutional identity to your SynDB account, automatically verifying you as an academic user:

Log in to SynDB
Navigate to CILogon verification (or GET /v1/user/authenticate/cilogon/authorize)
Authenticate with your institution’s SSO
Your account is marked as verified — unlocking SyQL, graph analysis, and upload

Service Accounts

For automated pipelines and integrations:

curl -X POST https://api.syndb.xyz/v1/user/auth/register-service \
  -H "Content-Type: application/json" \
  -H "X-Service-Secret: <SERVICE_SECRET>" \
  -d '{"email": "[email protected]", "password": "..."}'

Service accounts are auto-verified and bypass academic checks. The X-Service-Secret must match the server’s SERVICE_SECRET environment variable.

Logout

# Revokes the refresh token
curl -X POST https://api.syndb.xyz/v1/user/auth/logout \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "..."}'

Keyboard shortcuts

Synapse DB