Unified API
The Unified API is the programmatic entry point for DALP asset, compliance, servicing, and settlement operations. It exposes versioned API documentation, authenticated routes, tenant-scoped data access, and consistent request and response contracts for integration teams.
Overview
The Unified API lets you connect external systems to DALP platform operations without bypassing the controls that protect asset, compliance, servicing, and settlement workflows. The API is the programmatic counterpart to the Asset Console: requests authenticate the caller, resolve the relevant platform context, apply tenant scope where the route needs it, and return structured responses that integration code can handle.
The API exposes versioned documentation and OpenAPI specifications. /api/v2 serves the current interactive API explorer. /api/v2/spec.json serves the v2 OpenAPI document for client generation and external API tooling. /api redirects to the v2 explorer.
What the API is for
Use the Unified API when an integration needs to start, inspect, or automate DALP workflows from another system. Typical callers include issuer portals, back-office systems, compliance tooling, reporting pipelines, and controlled operational scripts.
| Integration need | API role | Boundary |
|---|---|---|
| Asset lifecycle work | Start or inspect operations such as creation, servicing, transfer, mint, burn, or pause when the route supports that operation | The API does not remove approval, signing, compliance, or on-chain validation steps. |
| Compliance and identity workflows | Read or update identity, claim, and compliance state through authenticated routes | The selected compliance provider, legal policy, and source evidence remain part of the operating model. |
| Platform administration | Read configuration, health, activity, and system-level state exposed by versioned routes | Administrative routes still require the right caller permissions and platform context. |
| External reporting | Pull indexed events, balances, assets, claims, and lifecycle data for downstream systems | Indexed reads reflect confirmed and processed platform state, not a promise that every upstream provider is healthy. |
Request path
The request path has four checkpoints.
- For DALP operation routes, the caller uses the matching versioned API surface, such as
/api/v2or a route listed in/api/v2/spec.json. Authentication flows are separate and use/api/auth/*. - Authenticated operation routes resolve the caller session and authorisation context before business logic runs.
- Tenant-scoped routes bind database access to the caller's tenant and, where needed, the resolved system address and chain.
- Route handlers use the path the endpoint needs: some read indexed platform state, some hand state-changing work to the execution layer, and some serve direct API work such as document download or bundler operations.
This separation matters during incident review. A failed request can be an authentication failure, a tenant-scope mismatch, a validation error, a direct-handler failure, an execution failure, an on-chain revert, or a stale indexed read. Treat those as different problems rather than retrying every failure as if it were temporary.
API documentation surfaces
Use the versioned endpoints for platform integration work. Auth flows are the exception: sign-in, session, and API-key routes live under /api/auth/*, not under a versioned /api/v1 or /api/v2 prefix.
| Endpoint | Purpose |
|---|---|
/api/v2 | Interactive API explorer for the current v2 surface. |
/api/v2/spec.json | OpenAPI JSON document for v2 client generation and external API tooling. |
/api/v1 | Interactive explorer for the v1 surface where legacy integrations still use it. |
/api/v1/spec.json | OpenAPI JSON document for v1 clients. |
/api/auth/* | Authentication flows such as sign-in, session, and API-key operations. |
Choose the documented surface that matches the integration contract you operate. Use the auth surface for caller identity flows, then check the route scope before you design caller permissions. Routes use different scopes depending on the data or operation they expose.
Route scopes
| Scope | What it means | Use it for |
|---|---|---|
| Public | The route does not require an authenticated caller. | Health or public metadata routes where no tenant data is exposed. |
| Authenticated | The route requires a resolved caller session and authorisation context. | User, account, and operational routes that depend on who is calling. |
| Tenant scoped | The route constrains database access to the caller's tenant and scoped platform context. | Asset, identity, compliance, and lifecycle reads or mutations that must not cross tenants. |
| System indexed | The route resolves system context and reads indexed platform state. | Activity, statistics, balances, and monitoring views backed by indexed chain and platform data. |
When you design an integration, map each call to the narrowest scope that can do the job. Do not use administrative or global routes for tenant workflows that have a scoped route.
Responses and errors
API responses are structured for machine handling. Validation failures, authentication failures, authorisation failures, missing resources, rate limits, and server-side errors use distinct HTTP status classes so client code can make the right next move.
| Category | HTTP status | Caller next step |
|---|---|---|
| Validation error | 400 | Fix the request shape, identifier, or field value before retrying. |
| Authentication failure | 401 | Reauthenticate or refresh the caller credentials. |
| Authorisation denied | 403 | Check the caller role, tenant, and platform permissions. |
| Resource not found | 404 | Verify the identifier and the tenant or system context used for the request. |
| Rate limited | 429 | Back off and retry after the advertised delay when provided. |
| Server error | 500 | Retry only when the operation is safe to repeat. Escalate with the request context if the error persists. |
For state-changing operations, check whether the route documents idempotency, execution status, or transaction tracking before retrying. A retryable transport error is not proof that the underlying operation did nothing.
Integration checklist
Before connecting an external system to the Unified API:
- Choose the versioned surface and generate or configure the client from the matching OpenAPI document.
- Confirm the caller has the roles needed for the exact tenant and system context it will use.
- Keep tenant identifiers, system addresses, chain IDs, and asset identifiers explicit in the integration design.
- Treat indexed reads, direct API handlers, and state-changing execution as separate paths with separate failure handling.
- Log request identifiers, route names, caller identity, tenant context, and response status in the external system.
- Define retry behaviour per route, especially for state-changing operations that can reach signing or on-chain submission.
See also
- API integration guide for implementation steps.
- Authentication for caller identity and API key management.
- Asset Console for the web interface that uses the same platform workflows.
- DALP Execution Engine for operation coordination and transaction execution.
- Platform flows for the path from request to execution, contract enforcement, and indexed evidence.
Asset Console
The Asset Console is DALP's authenticated web interface for asset lifecycle operations. It gives operators a guided view over asset design, holdings, compliance checks, and theme configuration while keeping execution, policy, and audit evidence in the platform services behind it.
System Factory
How DALP creates a system for an organization, keeps assets scoped to that system, and uses the token factory registry to isolate multi-tenant reads.