API reference

Every public endpoint the SQRL platform exposes: what each call does, who is allowed to make it, and the payloads it exchanges.

Updated 05 Aug 20265 min read

All calls go through a single API gateway, the same front door the SQRL web application uses. The gateway coordinates the platform's internal services: authentication, vaults and keys, tokens and contracts, spending policy, audit logging, and notifications. A small number of internal service-to-service endpoints exist but are not reachable with user credentials and are not documented here.

You do not need the API to operate SQRL. The web interface covers every operator workflow, and the rest of this documentation describes it. Use the API when you need to integrate SQRL with your own systems. For integration support beyond this reference, contact your Orobit representative.

Base URL

Every path on this page is relative to your organisation's gateway host. Your Orobit representative provides it during onboarding. The samples read it from a SQRL_API environment variable, so you can copy them without editing.

#Core concepts

These are the same terms the operator documentation uses. The Glossary defines each one in full; the table below covers how they surface in the API.

Term	What it means
Organisation	The top-level entity, usually a company or institution. Contains all workspaces, users, and resources.
Workspace	An isolated operating environment inside an organisation, set to a single Bitcoin network. Everything is scoped to a workspace, and data and permissions never cross workspace boundaries.
Vault	A shared, multi-signature asset container. Moving value requires several members to approve, not just one.
Token, or contract	A digital asset issued and governed by the organisation, anchored to Bitcoin for a tamper-proof history.
Movement, or transaction proposal	Any value-moving operation: a mint, burn, transfer, or token deployment. The API carries each one as a transaction proposal that collects approvals until the vault's threshold is met.
Signing key	A member's personal approval credential. The platform stores only the public part. Private keys never leave the member's own device. A member has one active key per Bitcoin network.
Signing profile, and profile address	A member's personal interface for the keys they sign with. The profile address is a personal Bitcoin address derived from the member's own key, used for example to receive purchased Bitcoin before it moves into a vault. Spending from it needs only that member's signature.
Whitelist	A list of approved destination addresses. There are two: a per-token whitelist enforced by the token itself, and a workspace Address Book of saved, named addresses.
Role	A named bundle of permissions assigned to a member within a workspace, for example Approver or Auditor.
Audit log	A permanent, unchangeable record of every significant action.

#Access levels

Every endpoint sits at one of three access levels, shown on each endpoint page.

Public

No sign-in required. Used for registration, sign-in, and service health.

Authenticated

The caller must be signed in and present an access token.

Permission-gated

The caller must be signed in and hold a specific permission in the workspace the request targets.

Signing in returns an access token. Authenticated endpoints expect it as a bearer token on every request:

bash

Authorization: Bearer <access-token>

Sessions are kept alive with POST /auth/refresh, which relies on a secure cookie set at sign-in.

Permissions carry the same names as in the application. The Permission reference lists them for operators; the API identifies them by key, for example MANAGE_WORKSPACE. GET /api/v1/list-all-permissions returns the authoritative list. The Owner role bypasses all permission checks.

Permission	What it lets a member do
`MANAGE_WORKSPACE`	Manage vaults, tokens, contracts, token whitelists, and vault limits, and change members' roles.
`MANAGE_USERS`	Invite and remove members, and view the member list.
`MANAGE_ROLE`	Edit role permissions and spending limits.
`MANAGE_PERMS`	Create roles and view the detailed role and permission setup.
`PAYMENT_INIT`	Start transfers, move their own deposited Bitcoin into a vault, view signing keys, and view their own limits.
`PAYMENT_APPROVE`	Review and approve pending movements.
`VIEW_BALANCES`	See vaults, token balances, and the Address Book, buy Bitcoin, and see their own purchase history.
`VIEW_LOGS`	View and export the audit log.

#Payload conventions

Authentication endpoints sit at /auth/… and are unversioned. Everything else sits under /api/v1/…. Service health is at /gateway/health and /health.

POST endpoints take a JSON body. GET endpoints take query parameters with the same names.
Ids are 64-bit integers unless a shape shows them as strings.
Spending limits and fiat amounts are decimal strings, for example "2500.75".
Token amounts marked raw units are integer strings already scaled by the token's decimals. For a token with two decimals, 1.5 tokens is "150".
Timestamps are RFC 3339 in UTC.
Some responses use capitalised field names and a nullable wrapper. nullable(string) on this site means { "String": "…", "Valid": true }, and likewise { "Time": …, "Valid": … } and { "Int64": …, "Valid": … }, where "Valid": false means no value is present. Each endpoint page shows the response exactly as it appears on the wire.

Shapes referenced by name across several endpoints, such as User, Vault, Key, and Contract, are defined once in Shared objects.

Error responses are not yet documented

Endpoint pages describe success responses. A per-endpoint list of error codes and their meanings is still being compiled from the gateway implementation and will be published here. Until then, treat any non-2xx status as a failure and surface the response body to the caller.

#Where to start

Exchange an email and password for an access token, then send it as a bearer token on every later call.

Create a vault

Set the approval threshold, the signer set, and the spending limit.

Propose and sign

Create a transaction proposal, then collect approvals until the threshold is met.

Was this page helpful?