Skip to Content
Onshore is in early access. Don’t load real customer data until the items in Known limits are closed.
DevelopersAuthentication

Authentication

Your systems call Onshore as service accounts. A service account has an Ed25519 key pair: you keep the private key on your server, and Onshore holds only the public key.

Make a key pair

./rv sa-keygen

It prints a public key and writes the private key (a seed) for your server. Keep the private key in your secret manager.

Add the service account

In the console, People → Add a person or service account → Service account. Give it a name, roles (usually backend_service), the public key, and optionally an IP allowlist. Note its service account ID and key ID.

Let it act

The backend-services starter rule lets backend_service store, insert, search and redact files. To reveal values, add an access rule for its role.

How a call is authenticated

The SDKs do this for you:

  1. Build a signed assertion: a JWT signed with EdDSA, with iss and sub set to the service account ID, aud set to onshore, a unique jti, an expiry within 5 minutes, and the key ID in the kid header.
  2. POST /v1/auth/token with {"assertion": "…"}. Each assertion works once.
  3. You get a bearer token valid for 15 minutes. Send it as Authorization: Bearer ….
ResponseMeans
200Token issued
401Signature, audience, expiry or replay check failed
403Your source IP isn’t on the key’s allowlist

Never put a private key in a browser or mobile app. Apps use single-use client tokens minted by your server. See Collect and reveal in the front end.

Signing an assertion yourself

Only needed in a language without an SDK, or to try the API reference by hand. The assertion is a standard JWT with EdDSA; any JWT library that supports Ed25519 works.

PartValue
Header{"alg": "EdDSA", "typ": "JWT", "kid": "<key id>"}
iss, subThe service account ID
audonshore
jtiA new random value each time
iatNow, in Unix seconds
expAt most 5 minutes after iat (the SDKs use 2)
import crypto from "node:crypto"; const seed = Buffer.from(process.env.ONSHORE_PRIVATE_KEY, "base64"); const key = crypto.createPrivateKey({ key: Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), seed]), // PKCS#8 wrapper for an Ed25519 seed format: "der", type: "pkcs8", }); const b64u = (o) => Buffer.from(JSON.stringify(o)).toString("base64url"); const now = Math.floor(Date.now() / 1000); const unsigned = `${b64u({ alg: "EdDSA", typ: "JWT", kid: process.env.ONSHORE_KEY_ID })}.${b64u({ iss: process.env.ONSHORE_SA_ID, sub: process.env.ONSHORE_SA_ID, aud: "onshore", jti: crypto.randomUUID(), iat: now, exp: now + 120, })}`; const assertion = `${unsigned}.${crypto.sign(null, Buffer.from(unsigned), key).toString("base64url")}`; const r = await fetch(`${process.env.ONSHORE_URL}/v1/auth/token`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ assertion }), }); const { access_token, expires_in } = await r.json(); // use as "Authorization: Bearer …" for 15 minutes

Rotating and revoking

Add a new key to the service account, switch your server to it, then revoke the old one on the person’s page. A revoked key stops working at once. Suspending the service account stops all its keys.

Rate limits on failures

Repeated authentication failures from one address are slowed (120 a minute by default, set by RV_AUTH_FAILURES_PER_MINUTE).

Last updated on