Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Authentication

SynDB has one way to create an account: sign in with an existing identity provider. There is no email sign-up form, no password, and no password reset. The sign-in page also shows email and password fields: those are for existing service accounts only. If you are new, use one of the buttons below.

Signing in

Open app.syndb.xyz and choose one of:

ButtonProviderAccount you get
Sign in with your institutionCILogon (university or research-institute login)Academic account, verified in one step. Being enabled: until then, use GitHub
Sign in with GitHubGitHubAcademic account, verified in one step

Both buttons create the account on first sign-in and mark it as an academic account immediately, which is what unlocks query execution, graph analysis, meta-analysis, jobs and upload. You never receive a verification email and never set a password.

If you lose access, sign in again with the same provider. There is no recovery link, because there is no SynDB password to recover.

What needs an account

ActionAcademic account needed
Browse datasets in the web appNo
GET /v1/neurodata/corpus, /datasets, /datasets/{id}, /schema/tablesNo
Run a SyQL query, graph analysis, meta-analysis, jobYes
Upload or edit a datasetYes, and you must own it
Federation or review admin pagesNo — those need an operator or reviewer role

The public HTTP API is at https://api.syndb.xyz; its interactive reference is at api.syndb.xyz/docs.

Command line login

The syndb CLI lives in the private repository, so install it first (see Installation).

syndb auth login github

The CLI opens your browser, you authorise GitHub, and the browser displays a JSON block with a token pair. Paste that whole block back into the terminal; the CLI verifies it against your profile and stores it in ~/.config/syndb/auth.json.

syndb auth login cilogon associates CILogon with the account the CLI is already logged in as. It reads the stored CLI token before it starts, so run syndb auth login github first (or another CLI login). Signing in through the browser at app.syndb.xyz does not populate the CLI credential store, so a web session alone is not enough. The command does not create an account.

Other commands:

syndb auth profile      # show the account behind the stored token
syndb auth refresh      # rotate the stored refresh token now
syndb auth logout       # delete the stored token on this machine
syndb auth show-token   # print the access token, for shell composition

syndb auth register still exists for operator-run local stacks, but it is not the path for the hosted service.

Tokens

The API uses PASETO v4 tokens.

  • Sign-in returns a short-lived access token and a longer-lived refresh token. Send the access token as Authorization: Bearer <token>.
  • The CLI and the Python client exchange the refresh token for a new pair automatically, so normal use does not hit an expiry.
  • Each refresh rotates the token pair: the old refresh token stops working. If a rotated token is replayed, the whole family is revoked and you have to sign in again.

For scripts, either reuse the stored login or set SYNDB_AUTH_TOKEN in the environment. The Python client checks, in order: a stored refresh token, ETL_USER_PASSWORD login, SYNDB_AUTH_TOKEN, then the token in ~/.config/syndb/auth.json.

Service accounts

Automated pipelines can use a service account instead of a person’s login. The server operator creates one with the shared service secret:

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": "pipeline@lab.org", "password": "..."}'

Service accounts are auto-verified and skip the academic check. The X-Service-Secret value must match the server’s configured secret; only the operator has it.

Logging out

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

syndb auth logout only deletes the token stored on your machine; it does not revoke it on the server. Use the logout endpoint above when you need the refresh token to stop working.