tRPC API

Overview

Most data in Rolebase is read and written through the GraphQL API, which is the recommended surface for integrations. Alongside it, the backend exposes a tRPC API: the typed RPC layer that the web app uses for operations that go beyond plain CRUD, such as creating an organization with its seed roles, archiving a circle and its descendants, exporting data, or inviting a member.

This section documents the procedures that are useful from outside the app, one page per router. Internal procedures (webhooks, scheduled jobs, search indexing) are listed for reference and are not meant to be called directly.

Endpoint

The tRPC API is served at the backend root:

• Production: https://api.rolebase.io
• Local development: http://localhost:8888

It speaks the standard tRPC HTTP protocol (queries over GET, mutations over POST), so it works with any tRPC client or with plain HTTP.

Authentication

tRPC procedures are authenticated with an API key, the same key the GraphQL API uses. Create one from Settings > API keys in the app and send it in the x-api-key header:

x-api-key: <your-api-key>

The procedures run with the permissions of the user the key belongs to. A few procedures are public (such as reading an invitation or a shared org), and the internal procedures use a webhook secret instead.

Type-safe client

The cleanest way to call the API is a typed tRPC client that imports the router type from the backend package:

import { createTRPCClient, httpBatchLink } from '@trpc/client'
import type { AppRouter } from '@rolebase/backend'

const trpc = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'https://api.rolebase.io',
      headers: () => ({
        'x-api-key': apiKey,
      }),
    }),
  ],
})

// Query
const data = await trpc.org.getPublicData.query({ orgId })

// Mutation
const { id } = await trpc.org.createOrg.mutate({ name: 'Acme', slug: 'acme' })

Raw HTTP

You can also call procedures over plain HTTP without a tRPC client.

# Query: GET /<procedure>?input=<url-encoded-json>
curl 'https://api.rolebase.io/org.getPublicData?input=%7B%22orgId%22%3A%22YOUR_ORG_ID%22%7D' \
  -H 'x-api-key: YOUR_API_KEY'

# Mutation: POST /<procedure> with the input as the JSON body
curl -X POST 'https://api.rolebase.io/circle.archiveCircle' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"circleId": "YOUR_CIRCLE_ID"}'

The response is wrapped as { "result": { "data": <value> } }.

Errors

A failed call answers with { "error": { "message": ..., "data": { "code": ..., "httpStatus": ... } } }, and a typed client throws a TRPCClientError carrying the same code. The codes are the same across every procedure, so the reference pages only mention what is specific to a procedure.

Procedures

Procedures are grouped in routers, and a call combines the router name and the procedure name: org.createOrg, circle.archiveCircle.

Next steps

• Browse the GraphQL API for entities, queries, and mutations.
• Try queries live in the GraphQL Playground.
• Set up the development environment to explore the backend source.