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:
| Button | Provider | Account you get |
|---|---|---|
| Sign in with your institution | CILogon (university or research-institute login) | Academic account, verified in one step. Being enabled: until then, use GitHub |
| Sign in with GitHub | GitHub | Academic 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
| Action | Academic account needed |
|---|---|
| Browse datasets in the web app | No |
GET /v1/neurodata/corpus, /datasets, /datasets/{id}, /schema/tables | No |
| Run a SyQL query, graph analysis, meta-analysis, job | Yes |
| Upload or edit a dataset | Yes, and you must own it |
| Federation or review admin pages | No — 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.