Information
- License: Apache-2.0
- OpenAPI version:
3.1.0
Overview
Buildinglinks Trust Authority v1
Section titled “Buildinglinks Trust Authority v1”The authority of the dataspace: onboarding, the participant registry, membership credentials (DCP), monitoring, the notary and disclosures. It never receives payload data or protocol messages. Its management API (/api/v1) is used by its UI and by bl authority; connectors call it with a DCP token. Operations carry x-cli: the bl authority command that offers them, or none with a reason (decisions #63). x-role is the role a caller needs.
Authentication
Section titled “Authentication”session
Section titled “session”The session of the management UI (backend for frontend, decisions #11 and #62). GET /auth/login starts an OpenID Connect login at the participant’s own identity provider; /auth/callback sets this HttpOnly cookie (SameSite=Lax, and Secure when the service’s public URL is https). The session lives on the server and checks back with the identity provider every 10 minutes, so a disabled account or a changed role counts within minutes. A change (POST, PUT, PATCH, DELETE) with this cookie must come from a page of the service itself: Sec-Fetch-Site: same-origin, or without that header an Origin (or else a Referer) on the service’s public URL; otherwise 403 cross_site_request (decisions #83).
Security scheme type: apiKey
Cookie parameter name: bl_authority_session
A session of the bl CLI (decisions #62): bl login runs the Device Authorization Grant (RFC 8628) at POST /api/v1/cli/device and POST /api/v1/cli/token. The opaque access token (10 minutes) and the rotating refresh token are bound to the CLI’s P-256 key with DPoP (RFC 9449): every request sends Authorization: DPoP <token> and a DPoP header with a fresh proof (htm, htu, iat within 60 s, a single-use jti, and ath, the hash of the token).
Security scheme type: http
bearer
Section titled “bearer”The break-glass token BL_ADMIN_TOKEN as Authorization: Bearer <token>, for development only. The authority has no API keys.
Security scheme type: http
A Self-Issued ID token (Decentralized Claims Protocol 1.0) of the calling participant’s connector, signed with the key of its DID, with the authority’s DID as audience. Every token is accepted once (jti) and lives at most 600 s. A strict authority (production, acceptance) also requires the connector’s environment in the BL-Environment header (decisions #39).
Security scheme type: http
Bearer format: JWT