Ontoshire

API tokens

Programmatic access to Ontoshire is authenticated; human browsing is open. The client and any script that pulls a schema, shapes, or a closure needs a token — for public and private ontologies alike.

This is a signup wall, not a paywall. Pulling public schemas is free — it just isn’t anonymous, so usage can be attributed and rate-limited fairly. Browsing the website and the public SPARQL endpoint stay open to everyone.

What a token is#

  • Read-only. A token can pull schemas, shapes, and closures — nothing else. It can never register repos, trigger ingestion, or touch billing.
  • Prefixed and hashed. Tokens start with ons_ (so leak scanners and humans recognise them) and are stored only as a hash — Ontoshire can’t show you a token again after creation.
  • Revocable, optionally expiring. Revoke anytime; set an expiry when you create it.

Local development — ontogate login#

The device flow is the easiest way to get a token on your own machine. No password is typed into the CLI; you approve in a browser you’re already signed into:

  1. Run ontogate login.
  2. The CLI prints a short code and a URL. Open the URL, confirm the code matches, and click Approve.
  3. The CLI receives the token and writes it to ~/.ontogate/credentials (file mode 0600). Done — future commands pick it up automatically.
ontogate login
$ ontogate login
To authorize this device, visit:

    https://ontoshire.com/activate

and enter the code:

    BCDF-GH23

Waiting for approval…
✓ Logged in. Token stored in ~/.ontogate/credentials.
Only approve a code you just generated yourself. Ontoshire never sends a one-click approval link — the code confirmation is the point where you consent.

CI & automation — Settings#

For a runner or a service, mint a token in the dashboard and store it as a secret:

  1. Go to Settings → API Tokens.
  2. Give it a label (e.g. ci-validation), optionally set an expiry, and Create.
  3. Copy the token — it’s shown once — and store it as a CI secret.

How the client finds your token#

Resolution order, first match wins:

  1. The --token flag.
  2. The ONTOGATE_API_TOKEN environment variable.
  3. The stored file at ~/.ontogate/credentials (written by ontogate login).
examples
# explicit
ontogate validate --token ons_… --schema acme/x@v1 --data d.ttl

# environment (CI)
export ONTOGATE_API_TOKEN=ons_…
ontogate validate --schema acme/x@v1 --data d.ttl

# stored (after ontogate login) — nothing to pass
ontogate validate --schema acme/x@v1 --data d.ttl
Never put a token in a URL or commit it. Use the Authorization: Bearer header (the client does this for you), environment secrets in CI, and the 0600 stored file locally.

Revoking#

Delete a token anytime from Settings → API Tokens. The next pull that uses it fails with an auth error (exit code 2). Rotating is just: create a new one, update the secret, revoke the old.