API reference · v1
v1 is the new canonical Aleta API and the default track for every new integration. It runs on a fresh host, returns errors in a different format, and is the first version with proper per-tenant isolation — one customer can no longer impact another's request budget.
Base URL
Every path in v1 is relative to https://api.aleta.io. v1 lives on its own host, separate from the legacy v2 and v3 prefixes — you can run a migration with both stacks live side-by-side.
Base URL
https://api.aleta.io
Hello, v1
curl https://api.aleta.io/v1/clients \
-H "Authorization: Bearer {access_token}"
What changed from v2 / v3
v1 is a clean rewrite, not an incremental bump. The deltas worth knowing before you start.
- Name
- One surface, one host
- Description
Replaces both legacy URL prefixes with a single canonical surface on its own host. No more split-prefix mental model.
- Name
- RFC 7807 errors
- Description
Every error response is a problem-details payload with the same shape on every endpoint. Legacy emits a JSON:API errors envelope; v1 doesn't.
- Name
- Per-tenant isolation
- Description
Rate limiting and concurrency budgets are scoped to the calling tenant, not the global pool. A misbehaving integration can't degrade anyone else's traffic.
- Name
- Cursor pagination
- Description
Every list endpoint takes a cursor and a limit and returns the next cursor in the response. No more page-numbered offsets, no more shifting results when data changes mid-walk.
- Name
- ETag caching
- Description
Read-heavy endpoints honour conditional requests. Clients that poll the same resource pay 304 instead of the full response when nothing has changed.
Resource groups
v1 is organised around Aleta's domain model rather than generic CRUD slices. Start with Clients — every other resource is scoped to a client.
- Name
- Clients
- Description
Clients own the data. Inside a client, the legal entity structure captures ownership; the reporting entity structure captures how the client wants to view it. Portfolios subdivide a reporting entity by grouping accounts and depositories into named buckets; accounts are the unit of custody; depositories describe where the assets physically sit.
- Name
- Custodian integration
- Description
How wealth data lands on the platform. Every account is linked to a custodian via an authority granted through an auth flow. The platform owns the consent lifecycle.
- Name
- Data
- Description
Holdings, transactions, and performance — what most integrators read out. They operate against reporting entities, the consolidated views the client has configured.
- Name
- Instruments
- Description
Everything you can hold — listed securities, private assets, derivatives, cash positions. Time-series data hangs off each instrument.
- Name
- Platform
- Description
Workspace identity (users) and event delivery (webhooks).
Authentication
v1 accepts the same access tokens that v2 and v3 already accept — no key rotation, no new credential flow. The legacy OAuth 2.0 JWT-Bearer exchange (RFC 7523) is unchanged: customers sign an assertion JWT with their ECDSA P-256 private key, exchange it at auth.aleta.io/oauth/token for an access token, and send that token as a bearer.
Existing API users can repoint requests at api.aleta.io/v1/... with the same access token already in their integration.
Authenticated request
curl https://api.aleta.io/v1/clients \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
Stability
v1 is the active track. Additive changes ship onto v1 without a new version. Breaking changes — when they eventually need to happen — open a new track that runs in parallel with v1 for at least 12 months before sunset is announced.
Migrating from v2 or v3
Both legacy prefixes are kept online for existing integrations. Nothing is forcing a same-day migration — but new integrations should default to v1, and v3 features will not backfill into v1 endpoints. The v3 reference and v2 reference document what's still served on the legacy host.