No description https://unilayer.dev
  • C# 96.3%
  • Shell 3.6%
  • Dockerfile 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
ferociousbyte 1a560f7903
Some checks failed
/ build (push) Failing after 1m59s
/ push (push) Has been skipped
libs/raft at 1df2c26: what waits for a node's loop is bounded, a connection ends with its certificate, and damage in the durable part of the log is refused
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-17 20:05:29 +01:00
.forgejo/workflows A release of unilayer requires libs/raft at one of its release tags, as client and storage 2026-11-15 11:19:41 +01:00
docs A cluster can say which node a certificate is for, and which certificates it no longer trusts 2026-11-17 19:26:12 +01:00
libs libs/raft at 1df2c26: what waits for a node's loop is bounded, a connection ends with its certificate, and damage in the durable part of the log is refused 2026-11-17 20:05:29 +01:00
scripts A cluster can say which node a certificate is for, and which certificates it no longer trusts 2026-11-17 19:26:12 +01:00
src A cluster can say which node a certificate is for, and which certificates it no longer trusts 2026-11-17 19:26:12 +01:00
tests A cluster can say which node a certificate is for, and which certificates it no longer trusts 2026-11-17 19:26:12 +01:00
.dockerignore unilayer.Cluster on the official DotNext.Net.Cluster 6.11.0, which has our fix (dotnet/dotNext#307) 2026-10-27 22:43:00 +01:00
.gitignore Ignore the files of a local run 2026-10-23 20:29:04 +02:00
.gitmodules A Raft of our own begins as the submodule libs/raft 2026-11-12 22:35:05 +01:00
Architecture.md After the two Valkeys: a health check for the store, the cache without what a replica needed 2026-11-11 17:22:41 +01:00
CHANGELOG.md A cluster can say which node a certificate is for, and which certificates it no longer trusts 2026-11-17 19:26:12 +01:00
CLA.md Add licensing files and contribution guidelines 2026-09-29 22:47:22 +02:00
compose.yaml The storage and client audit on the server's side, and both submodules to their latest main 2026-10-25 00:29:37 +02:00
CONTRIBUTING.md End-to-end tests of uploads and downloads through the storage service 2026-10-23 17:20:14 +02:00
Dockerfile The API image runs as its own user, and compose's Valkey has a password 2026-10-24 15:37:03 +02:00
LICENSE Add licensing files and contribution guidelines 2026-09-29 22:47:22 +02:00
README.md A leader's handover costs no request, and the start waits for the database 2026-11-12 07:31:04 +01:00
unilayer.slnx A load test for the cluster: what a 3-node cluster writes and reads, and where it stops 2026-11-11 07:09:21 +01:00

unilayer

A modular REST API interface designed to provide secure, scalable, and maintainable access to Collections (database tables), Assets (files), and Users (the clients of the API – apps, services, scripts – with their roles and permissions). Acts as an intermediary layer between client applications and backend systems (database, storage, cache).

Features

  • Dynamic Collections: Create and manage database tables at runtime via REST API
  • Asset Management: Upload, store, and retrieve files with configurable storage backends
  • API Users: One per app or service, not the end users of your app (no sign-up, login or password); role-based access control, every user has an opaque bearer token, next to a static token for the operator
  • Permission System: String-based permissions with policy and role management via REST API
  • Caching: Built-in Valkey support for performance optimization
  • Multi-backend Support: PostgreSQL, Valkey, files through the storage service (or local / S3-compatible storage)
  • GraphQL next to REST, and a cluster mode (Raft) for several nodes

Documentation

Requirements

  • .NET 10.0 SDK
  • PostgreSQL 14+
  • Valkey (Redis-compatible) 7.0+
  • Optional: MinIO or S3-compatible storage for cloud storage

Installation

PostgreSQL

macOS (Homebrew):

brew install postgresql@16
brew services start postgresql@16

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Windows (Chocolatey):

choco install postgresql16

Create a database and user:

CREATE DATABASE unilayer;
CREATE USER unilayer_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE unilayer TO unilayer_user;

Valkey

macOS (Homebrew):

brew install valkey
brew services start valkey

Ubuntu/Debian:

sudo apt update
sudo apt install valkey-server
sudo systemctl start valkey-server
sudo systemctl enable valkey-server

Windows: Download from Valkey releases and run as service.

Docker:

docker run -d --name valkey -p 6379:6379 -v valkey-data:/data valkey/valkey

MinIO (Optional - for S3 storage)

Docker:

docker run -d -p 9000:9000 -p 9001:9001 minio/minio server /data --console-address ":9001"

Access the MinIO console at http://localhost:9001 (default credentials: minioadmin/minioadmin).

Configuration

Create an appsettings.yaml file in the project root:

# Server configuration
endpoint: "0.0.0.0:5380"

# Authentication
authentication:
  staticApiToken: "your-secure-api-token"

# Database configuration (PostgreSQL example)
database:
  connectionString: "Host=localhost;Database=unilayer;Username=unilayer_user;Password=your_secure_password;Port=5432"

# Valkey configuration
valkey:
  host: "localhost"
  port: 6379
  password: ""
  database: 0
  keyPrefix: "unilayer:"

# Storage configuration (Local filesystem)
storage:
  provider: "local"

local:
  path: "./storage/assets"

# Alternative: MinIO/S3 storage
# storage:
#   provider: "minio"
# s3:
#   endpoint: "http://localhost:9000"
#   accessKey: "minioadmin"
#   secretKey: "minioadmin"
#   bucketName: "unilayer-assets"
#   useSsl: false              # unset: HTTPS unless the endpoint is local
#   createBucketIfNotExists: true

Configuration Options:

Component Config Path Description
Database database:startupWaitSeconds How long the start waits for a database server that does not take connections yet (default 60; 0 ends at once).
Database database:connectionString Connection string for the database. Leave Max Auto Prepare unset: the collections are read with SELECT *, and a statement prepared before a schema change fails afterwards (0A000); measured, it gained nothing.
Valkey valkey:host Valkey server hostname
Valkey valkey:port Valkey server port
Valkey valkey:password Valkey authentication password
Valkey valkey:user (UNILAYER_VALKEY_USER) ACL user of the connections, when not the default user
Cache cache:host (UNILAYER_CACHE_HOST) A second Valkey that only caches; valkey:* then keeps the volatile collections alone. Optional for one node, needed by every node of a cluster. Also cache:port, cache:password, cache:user, cache:database, cache:ssl
Valkey valkey:maxValueLength (UNILAYER_VALKEY_MAXVALUELENGTH) The longest value cached, in characters (default 2 MiB); a longer one - a large page with its references - is read from the database each time. /metrics counts hits, misses, errors and values too large in unilayer_cache_operations_total.
Valkey valkey:database Valkey database number (default 0)
Valkey valkey:keyPrefix (UNILAYER_VALKEY_KEYPREFIX) Prefix of every key the server writes, unilayer: by default; give each instance sharing a Valkey its own. The storage service writes under unilayer-storage:.
Collections collections:cacheTtlMinutes (5), collections:maxPageSize (1000), collections:maxBulkItems (1000) How long lists and items stay cached, the largest page, the most items of one bulk write
Collections collections:autoCreateTables (true) Whether a write to a missing collection creates it, and whether collections can be created at all
Users users:cacheTtlMinutes (5), users:defaultRole (user) Cache lifetime of users, the role of a user created without one
Permissions permissions:cacheTtlMinutes (5) How long a role's permission set stays cached in Valkey
Audit audit:enabled (true) Whether security-relevant actions are written to systemauditlogs
Assets assets:maxFileSizeBytes (100 MiB), assets:maxCachedContentBytes (1 MiB), assets:metadataCacheTtlMinutes / assets:contentCacheTtlMinutes (5) The largest upload, the largest content kept in the cache, and how long metadata and content stay there
Storage storage:provider service (the default: the storage service, storage:service:url required), local or minio/s3 (content through the API, on their way out) or none - see docs/Assets.md
Storage storage:quotaBytes (UNILAYER_STORAGE_QUOTABYTES) The most all assets may take together; 0 (default) for no limit. An upload or a restore beyond it is refused with 507 STORAGE_QUOTA_EXCEEDED. Deleted assets don't count until they are purged (assets:retention:*, see docs/Assets.md). /metrics reports unilayer_assets_size_bytes and unilayer_assets_quota_bytes.
Local Storage local:path Base directory for file storage
MinIO/S3 s3:endpoint MinIO/S3 endpoint URL
MinIO/S3 s3:accessKey Access key for authentication
MinIO/S3 s3:secretKey Secret key for authentication
MinIO/S3 s3:bucketName Bucket name for storage
Authentication authentication:staticApiTokenSecondary A second static token accepted next to staticApiToken, for rotating it (see Authentication)
TLS tls:certificatePath / tls:certificatePassword Server certificate (PKCS#12) of the API; with it the API is served over HTTPS
TLS tls:reloadIntervalSeconds How often the certificate files are checked for a renewal (default 30; 0: never, a renewal needs a restart)
Metrics metrics:endpoint ip:port of a separate listener serving /metrics (Prometheus); empty: off (see Metrics)
Network network:knownProxies (UNILAYER_NETWORK_KNOWNPROXIES) Reverse proxies in front of the API, comma-separated addresses or networks (10.0.0.0/8): their X-Forwarded-For names the client, so rate limits and the sign-in throttle count per client; empty: the header is ignored
Rate limits rateLimit:globalPerMinute (1000), rateLimit:writesPerMinute (50) Requests and writes per client and minute. They are counted on each node: behind a load balancer over several nodes a client gets up to that many per node
Idempotency idempotency:enabled / idempotency:retentionHours The Idempotency-Key header (default on) and how long keys are remembered (default 24)
Compression compression:enabled (UNILAYER_COMPRESSION_ENABLED) Brotli/gzip compression of JSON and other text responses (default on). Set to false when a reverse proxy compresses
Compression compression:level (UNILAYER_COMPRESSION_LEVEL) fastest (default), optimal or smallest
Compression compression:mimeTypes (UNILAYER_COMPRESSION_MIMETYPES) Comma-separated MIME types that replace the default list of text-like types

Quick Start

docker compose up -d runs PostgreSQL, Valkey, the API and the storage service together (see compose.yaml). To run the API from source:

  1. Clone with submodules (git clone --recurse-submodules, or git submodule update --init in an existing clone): the client and the shared models come from libs/client, the storage service from libs/storage
  2. Install dependencies (PostgreSQL, Valkey)
  3. Create appsettings.yaml with your configuration
  4. Run database migrations (automatic on startup)
  5. Start the API:
dotnet run --project src/unilayer

The API listens on http://localhost:5380; the API reference (Scalar) is at http://localhost:5380/api/v1, the OpenAPI document at /api/v1/openapi/v1.json.

Docker

docker compose up -d is the way to run it (see Quick Start). The image is built from a published server - the Dockerfile copies publish/, it doesn't compile:

dotnet publish src/unilayer -c Release -r linux-x64 --self-contained false -o publish
docker build -t unilayer .

The container needs at least a database and Valkey: UNILAYER_DATABASE_CONNECTIONSTRING, UNILAYER_VALKEY_HOST (and UNILAYER_VALKEY_PASSWORD), and UNILAYER_AUTHENTICATION_STATICAPITOKEN for the first sign-in. Its liveness and readiness are /health/live and /health/ready.

API Overview

Base URL: /api/v1

Endpoint Method Description Required Permission
/collections GET List all collections collections:read
/collections/{name} GET Get all items in a collection collections:read, collections:{scope}:read or collections:{scope}:{name}:read
/collections/{name}/info GET Get collection metadata and fields collections:read
/collections POST Create a collection: {"name": ..., "fields": [...]} collections:write
/collections/{name} POST Add an item (creates the collection from it with collections:autoCreateTables) collections:write, collections:{scope}:write or collections:{scope}:{name}:write
/collections/{name}/count GET Count the items, optionally matching ?filter= collections:read, collections:{scope}:read or collections:{scope}:{name}:read
/collections/{name}/bulk POST Add up to 1,000 items in one transaction (one write against the rate limit) collections:write, collections:{scope}:write or collections:{scope}:{name}:write
/collections/{name}/bulk PUT Update up to 1,000 items in one transaction: {"ids": [...], "entities": [...]} collections:write, collections:{scope}:write or collections:{scope}:{name}:write
/collections/{name}/bulk/delete POST Delete up to 1,000 items by id; returns how many were deleted collections:write, collections:{scope}:write or collections:{scope}:{name}:write
/assets GET List all assets assets:read
/assets/{uid} GET Download an asset (optional image modifiers) assets:read
/assets POST Upload an asset assets:write
/assets/{uid}/upload-session, .../complete POST Upload content through the storage service (see docs/Assets.md) assets:write
/assets/{uid}/download-url GET A download URL of the storage service assets:read
/storage/keys GET The public key the storage service checks tokens with none
/users GET List all users users:read
/users POST Create a new user users:write
/users/{id} GET Get a specific user users:read
/users/{id} DELETE Delete a user users:write
/users/{id}/role PUT Update a user's role users:write
/roles GET List all roles security:read
/roles POST Create a new role security:write
/roles/{nameOrId} GET Get a specific role security:read
/roles/{roleId} PUT Update a role security:write
/roles/{roleId} DELETE Delete a role security:write
/roles/{roleId}/policies/{policyId} POST Assign policy to role security:write
/roles/{roleId}/policies/{policyId} DELETE Remove policy from role security:write
/policies GET List all policies security:read
/policies POST Create a new policy security:write
/policies/{nameOrId} GET Get a specific policy security:read
/policies/{policyId} PUT Update a policy security:write
/policies/{policyId} DELETE Delete a policy security:write
/policies/{policyId}/permissions/{permission} POST Add permission to policy security:write
/policies/{policyId}/permissions/{permission} DELETE Remove permission from policy security:write

See the full API documentation for detailed endpoint specifications.

Query Parameters

The collections list endpoint supports the following query parameters:

Parameter Type Description
limit integer Maximum number of items to return (default: 100)
offset integer Number of items to skip (default: 0)
fields string Comma-separated list of fields to include
sort string Sort order for results
filter string Filter expression

Sort Parameter:

  • No sort: Orders by unilayer_index ASC (insertion order)
  • sort=asc: Orders by unilayer_index ASC
  • sort=desc: Orders by unilayer_index DESC
  • sort=fieldname: Orders by fieldname ASC
  • sort=fieldname:asc: Orders by fieldname ASC
  • sort=fieldname:desc: Orders by fieldname DESC
  • sort=field1,field2:desc: Orders by field1 ASC, field2 DESC

Response Format

All collection item responses are wrapped with system metadata separated from user data to prevent field name collisions.

Single Item Response

{
  "data": {
    "name": "Test Item",
    "description": "A test item"
  },
  "metadata": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "index": 1,
    "createdAt": "2024-01-01T10:00:00Z",
    "updatedAt": null
  }
}

Multiple Items Response

{
  "data": [
    {"name": "Item 1", "description": "First item"},
    {"name": "Item 2", "description": "Second item"}
  ],
  "metadata": {
    "count": 2,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Collection Info Response

{
  "name": "mycollection",
  "tableName": "unilayer_mycollection",
  "createdAt": "2024-01-01T10:00:00Z",
  "updatedAt": null,
  "isSystem": false,
  "fields": [
    {"name": "name", "type": "TEXT", "nullable": false},
    {"name": "description", "type": "TEXT", "nullable": true}
  ],
  "systemFields": [
    {"name": "unilayer_id", "columnName": "unilayer_id", "type": "UUID", "isPrimaryKey": true, "isNullable": false},
    {"name": "unilayer_index", "columnName": "unilayer_index", "type": "BIGSERIAL", "isPrimaryKey": false, "isNullable": false},
    {"name": "unilayer_created_at", "columnName": "unilayer_created_at", "type": "TIMESTAMP", "isPrimaryKey": false, "isNullable": false},
    {"name": "unilayer_updated_at", "columnName": "unilayer_updated_at", "type": "TIMESTAMP", "isPrimaryKey": false, "isNullable": true}
  ]
}

Note: System fields (unilayer_id, unilayer_index, unilayer_created_at, unilayer_updated_at) are automatically managed by unilayer and cannot be defined by users. Field names starting with unilayer_ are reserved.

Authentication

Authentication uses Bearer tokens. Include the token in the Authorization header:

Authorization: Bearer your-secure-api-token

Rotating the static token

authentication:staticApiTokenSecondary (UNILAYER_AUTHENTICATION_STATICAPITOKENSECONDARY) is a second static token that is accepted next to authentication:staticApiToken. To replace the token without downtime: set the new token as the secondary one and restart, switch the clients to it, then make it the primary token, clear the secondary one and restart again. Both tokens give the admin role; both may be configured in plaintext or hashed.

The root user follows the primary token: at every start it is keyed to authentication:staticApiToken, so the old token stops working with that last restart - also in a database that was restored from the backup of another instance, whose root user arrives with that instance's token.

Retrying writes safely: Idempotency-Key

Send any unique string (e.g. a UUID) in the Idempotency-Key header of a POST, PUT, PATCH or DELETE, and the request may be retried - after a timeout, a dropped connection, a 503 - without being applied twice:

  • the first request runs and its response is remembered for idempotency:retentionHours (default 24);
  • a retry with the same key gets that response again, with the header Idempotent-Replay: true, and nothing is written;
  • a retry with the same key but another body gets 422: a key stands for one request, not for its route;
  • a second request with the same key while the first is still running gets 409;
  • a response with a 5xx status is not remembered: the retry runs again.

A key belongs to the caller, the method and the path; the same key from another user or on another route is another request. Responses larger than idempotency:maxResponseBytes (default 64 KB) are replayed with their status and without the body. In cluster mode the keys are part of the replicated data, so a retry is recognized by whichever node is the leader by then (see docs/Cluster.md, Consistency).

Metrics

With metrics:endpoint (UNILAYER_METRICS_ENDPOINT, e.g. 0.0.0.0:9464) the server opens a second listener that serves /metrics in the Prometheus text format and nothing else. It is plain HTTP without authentication: keep it inside the network of your monitoring system. The API port never serves the metrics.

Metric Meaning
unilayer_http_requests_total{method,status} Requests served, by method and status class (2xx, ...)
unilayer_http_request_duration_seconds{method} Histogram of the request duration
unilayer_database_size_bytes Size of the PostgreSQL database (read at most once a minute)
unilayer_assets_optimized_total, _optimize_skipped_total{reason}, _optimize_failed_total Image versions given an optimized copy, left without one, or failed (with assets:optimize:enabled, see docs/Assets.md)
unilayer_assets_optimize_saved_bytes_total, unilayer_assets_optimized_copies_bytes Bytes the copies saved, and bytes held in copies (not part of the quota)
unilayer_assets_image_downloads_total{source} Downloads of JPEG/PNG/GIF assets served from the optimized copy or the original
unilayer_assets_optimize_backfill_remaining Assets the running backfill pass has still to look at
unilayer_uptime_seconds, unilayer_process_working_set_bytes, unilayer_info{version} The process
unilayer_cluster_role{role} 1 for the node's role (leader, follower, candidate)
unilayer_cluster_has_leader 1 while the node knows the leader; 0 means an election or a lost majority
unilayer_cluster_term, _last_index, _commit_index, _applied_index The state of the replicated log
unilayer_cluster_apply_lag_entries Committed entries the node has not applied yet (replication lag)
unilayer_cluster_members, unilayer_cluster_members_available Members, and how many the node reached last (meaningful on the leader)
unilayer_cluster_snapshot_age_seconds, _snapshot_index, _snapshot_size_bytes The node's last snapshot
unilayer_cluster_certificate_expiry_timestamp_seconds When the node certificate or the cluster CA expires

The unilayer_cluster_* series exist in cluster mode only.

Permission System

unilayer uses a string-based permission system with roles and policies:

  • Policies contain a list of permission strings (e.g., collections:read, assets:write)
  • Roles are assigned one or more policies
  • Users are assigned a single role
  • Write permissions automatically imply read permissions (e.g., collections:write includes collections:read)
  • A collection's scope is the part of its name before the first underscore, its name in a permission the rest. A permission covers the levels below it: collections:write every collection, collections:shop:write every collection of the scope, collections:shop:order_items:write that one collection. Whoever grants permissions through policies needs each of them themselves.

Permission String Format

Permission Description
collections:read Read all collections
collections:write Create/update/delete all collections
collections:{scope}:read Read the collections of a scope: collections:shop:read covers shop and every shop_...
collections:{scope}:write Write the collections of a scope
collections:{scope}:{name}:read Read one collection: collections:shop:order_items:read is shop_order_items
collections:{scope}:{name}:write Write one collection
assets:read Read all assets
assets:write Create/update/delete all assets
assets:purge Remove deleted assets for good (DELETE /assets/{uid}?purge=true)
users:read Read all users
users:write Create/update/delete all users
security:read Read all roles and policies
security:write Create/modify/delete roles and policies

Built-in Immutable Entities

On first startup, unilayer automatically creates:

  1. fullaccess policy - Contains all permissions (collections:read, collections:write, assets:read, assets:write, assets:purge, users:read, users:write, security:read, security:write, cluster:admin); a permission added in a later version is added to it at the next start
  2. admin role - Assigned the fullaccess policy, immutable
  3. root user - Created from the static API token in configuration, assigned the admin role

Note: While a static API token is configured, the root user's token is that token: unilayer checks it at every start and re-keys the root user when it differs (a rotated token, a database restored from another instance). A token renewed for the root user through the API therefore only lasts until the next start. Without a configured static token the root user keeps the token stored in the database.

Default Roles

  • admin - Full access to all system resources (immutable)
  • user - Default role for new users (configurable)

API Examples

Authentication

All requests require a valid Bearer token:

# Using the root user token (from initial configuration)
ROOT_TOKEN="your-initial-static-token"

# Or use a token from a created user
USER_TOKEN="user-specific-token"

curl -H "Authorization: Bearer $ROOT_TOKEN" \
  http://localhost:5380/api/v1/users

Creating a New User

curl -X POST \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "john", "role": "user"}' \
  http://localhost:5380/api/v1/users

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "john",
  "role": "user",
  "apiToken": "generated-token-for-john",
  "createdAt": "2026-08-30T20:00:00Z"
}

Creating a New Policy

curl -X POST \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read-only",
    "description": "Read-only access to collections and assets",
    "permissions": [
      "collections:read",
      "assets:read"
    ]
  }' \
  http://localhost:5380/api/v1/policies

Response:

{
  "id": "12345678-1234-5678-1234-567812345678",
  "name": "read-only",
  "description": "Read-only access to collections and assets",
  "createdAt": "2026-08-30T20:00:00Z",
  "isImmutable": false,
  "permissions": ["collections:read", "assets:read"]
}

Creating a New Role

curl -X POST \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "viewer",
    "description": "View-only role"
  }' \
  http://localhost:5380/api/v1/roles

Response:

{
  "id": "87654321-4321-8765-4321-876543218765",
  "name": "viewer",
  "description": "View-only role",
  "createdAt": "2026-08-30T20:00:00Z",
  "isImmutable": false,
  "policies": []
}

Assigning a Policy to a Role

# Get the policy ID and role ID first
POLICY_ID="12345678-1234-5678-1234-567812345678"
ROLE_ID="87654321-4321-8765-4321-876543218765"

curl -X POST \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  http://localhost:5380/api/v1/roles/$ROLE_ID/policies/$POLICY_ID

Adding a Permission to a Policy

POLICY_ID="12345678-1234-5678-1234-567812345678"

curl -X POST \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  http://localhost:5380/api/v1/policies/$POLICY_ID/permissions/users:read

Listing All Roles

curl -H "Authorization: Bearer $ROOT_TOKEN" \
  http://localhost:5380/api/v1/roles

Response:

[
  {
    "id": "00000000-0000-0000-0000-000000000002",
    "name": "admin",
    "description": "System administrator with full access. This role is immutable.",
    "createdAt": "2026-08-30T19:52:57Z",
    "isImmutable": true,
    "policies": ["fullaccess"]
  },
  {
    "id": "87654321-4321-8765-4321-876543218765",
    "name": "viewer",
    "description": "View-only role",
    "createdAt": "2026-08-30T20:00:00Z",
    "isImmutable": false,
    "policies": ["read-only"]
  }
]

Listing All Policies

curl -H "Authorization: Bearer $ROOT_TOKEN" \
  http://localhost:5380/api/v1/policies

Response:

[
  {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "fullaccess",
    "description": "Full access to all system resources, collections, assets, users, and security settings",
    "createdAt": "2026-08-30T19:52:57Z",
    "isImmutable": true,
    "permissions": [
      "collections:read",
      "collections:write",
      "assets:read",
      "assets:write",
      "users:read",
      "users:write",
      "security:read",
      "security:write"
    ]
  }
]

Getting Current User's Permissions

curl -H "Authorization: Bearer $ROOT_TOKEN" \
  http://localhost:5380/api/v1/users/me/permissions

Response:

[
  "collections:read",
  "collections:write",
  "assets:read",
  "assets:write",
  "users:read",
  "users:write",
  "security:read",
  "security:write"
]

Maintenance commands

The server binary also runs one-off commands, then exits; unilayer --help lists them.

unilayer --truncate-all --dry-run       # lists the collections it would delete
unilayer --truncate-all --yes           # deletes every collection; users, permissions, history stay
unilayer --reinitialize-database --yes  # drops every table; the next start sets the database up again

The destructive ones (--truncate-all, --reinitialize-database, --remove-optimized-assets) only change anything with --yes, and refuse in cluster mode except --remove-optimized-assets. For --import-history-file, pass the target's token in UNILAYER_IMPORT_TARGET_TOKEN or --import-target-token-file=<path>, not on the command line.

Supported Backends

Component Supported Backends
Database PostgreSQL
Storage Local Filesystem, MinIO/S3
Cache Valkey

License

unilayer is open source. The repository uses two licenses:

Component Path License
Server (API, cluster, GraphQL, schema) everything not listed below AGPL-3.0-only
.NET client (Unilayer.Client) and shared models (Unilayer.Models) unilayer/client, here as libs/client/ MIT
Storage service (unilayer.Storage) unilayer/storage, here as libs/storage/ AGPL-3.0-only

Each submodule is covered by the license of its own repository; everything else is covered by the root LICENSE.

What this means in practice:

  • Self-hosting unilayer is free, including for commercial use.
  • The client and models can be used in any application, including closed-source and commercial ones. Using the client does not put your application under the AGPL.
  • If you modify the server and let others use it over a network, e.g. by offering it as a hosted service, you must make your modified source code available to those users under the AGPL.

Commercial support is available from Talaryon Labs.

Copyright (c) 2026 Talaryon Labs.

Contributing

Contributions are welcome. See CONTRIBUTING.md.