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-keygenIt 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:
- Build a signed assertion: a JWT signed with EdDSA, with
issandsubset to the service account ID,audset toonshore, a uniquejti, an expiry within 5 minutes, and the key ID in thekidheader. POST /v1/auth/tokenwith{"assertion": "…"}. Each assertion works once.- You get a bearer token valid for 15 minutes. Send it as
Authorization: Bearer ….
| Response | Means |
|---|---|
| 200 | Token issued |
| 401 | Signature, audience, expiry or replay check failed |
| 403 | Your 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.
| Part | Value |
|---|---|
| Header | {"alg": "EdDSA", "typ": "JWT", "kid": "<key id>"} |
iss, sub | The service account ID |
aud | onshore |
jti | A new random value each time |
iat | Now, in Unix seconds |
exp | At most 5 minutes after iat (the SDKs use 2) |
Node.js (no SDK)
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 minutesRotating 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).