ORRIN
Sign inStart free

Developers

From install
to publish in six steps

This is the intended integration flow. The widget, the npm package and the console are not published yet, so every snippet on this page is a draft contract and names may change before the first release.

Draft integration contract

Step 1

Install
the widget

A script tag plus one initialization call, or the npm package for React apps. The assistant opens on Cmd K or Ctrl K, or from a launcher button you place.

Script tag
<!-- Two lines in your product. Cmd K opens the assistant. -->
<script src="https://cdn.orrin.example/v1/orrin.js" data-workspace="ws_maple_court"></script>
<script>Orrin.init({ token: () => fetch("/api/orrin-token").then((r) => r.text()) });</script>
Reactnpm package, draft
import { OrrinAssistant } from "@orrin/widget";

export function App() {
  return <OrrinAssistant workspace="ws_maple_court" token={() => fetch("/api/orrin-token").then((r) => r.text())} />;
}

Step 2

Mint tokens
on your backend

Orrin never sees your users’ passwords or sessions. Your backend signs a short lived token with the claims below, and the widget sends it with every request. Orrin calls your API as that user.

Token claims

sub
The end user’s id in your system
company
The end customer company the user belongs to
role
The user’s role in your product
scopes
What the user may do, as a space separated list
exp
Five to fifteen minutes after iat
aud
orrin
kid
The key id you registered in the console
JavaScriptNode, jose
// Node with jose. The token lives ten minutes and is signed with your key.
import { SignJWT } from "jose";

app.get("/api/orrin-token", requireSession, async (req, res) => {
  const token = await new SignJWT({ sub: req.user.id, company: req.user.companyId, role: req.user.role, scopes: req.user.scopes })
    .setProtectedHeader({ alg: "EdDSA", kid: ORRIN_KEY_ID })
    .setIssuedAt()
    .setExpirationTime("10m")
    .setAudience("orrin")
    .sign(privateKey);
  res.type("text/plain").send(token);
});
PythonFastAPI, PyJWT
# FastAPI with PyJWT. The token lives ten minutes and is signed with your key.
import time
import jwt

@app.get("/api/orrin-token", response_class=PlainTextResponse)
def orrin_token(user: User = Depends(current_user)):
    now = int(time.time())
    claims = {"sub": user.id, "company": user.company_id, "role": user.role, "scopes": user.scopes,
              "iat": now, "exp": now + 600, "aud": "orrin"}
    return jwt.encode(claims, ORRIN_PRIVATE_KEY, algorithm="EdDSA", headers={"kid": ORRIN_KEY_ID})
C#ASP.NET Core
// ASP.NET Core minimal API. The token lives ten minutes and is signed with your key.
app.MapGet("/api/orrin-token", (ClaimsPrincipal user) =>
{
    var descriptor = new SecurityTokenDescriptor
    {
        Subject = new ClaimsIdentity(new[]
        {
            new Claim("sub", user.FindFirstValue("id")!),
            new Claim("company", user.FindFirstValue("companyId")!),
            new Claim("role", user.FindFirstValue("role")!),
            new Claim("scopes", string.Join(" ", user.FindAll("scope").Select(c => c.Value))),
        }),
        Audience = "orrin",
        Expires = DateTime.UtcNow.AddMinutes(10),
        SigningCredentials = new SigningCredentials(orrinKey, SecurityAlgorithms.EcdsaSha256),
    };
    return Results.Text(new JsonWebTokenHandler().CreateToken(descriptor));
}).RequireAuthorization();

Step 3

Import
your OpenAPI file

Upload or link your OpenAPI specification in the console. Each endpoint becomes a candidate tool with a name, a description and typed parameters taken from your schema. Nothing is exposed until you choose it.

Step 4

Label
your actions

Mark each exposed endpoint Read, Write or Sensitive, then map the property templates to your endpoints. Write shows a preview and waits for Confirm. Sensitive adds a typed confirmation word.

Step 5

Run
the test suite

Add your own questions and action scenarios to the starter suite and run it in Staging. You get grounded answer rate, citation accuracy, tool choice, parameters, confirmation compliance and policy refusals per version.

Step 6

Publish
to production

Compare versions side by side and publish. The console refuses to publish if confirmation compliance is below one hundred percent or any policy test fails.

Documentation

Full docs arrive
with the first release

There is no public reference documentation yet. Design partners get the integration guide, the token verification details and the OpenAPI import rules directly during onboarding, and the public docs are written from that work.

Integrate as a design partner