Artspect Shell API
The Shell API is a centralized authentication and authorization service. It is the single source of truth for who a user is (identity), what features exist (the catalog), and what a given user is allowed to do (resolved permissions).
Many independent applications — built by Koala42 and by third-party software houses — connect to one Shell API instance. Each application brings its own backend and frontend, but they all delegate login and permission decisions to the Shell.
Who this is for
This documentation is written for engineers integrating an application with the Shell API — whether you are building the frontend, the backend, or both. It assumes you are not modifying the Shell itself, only consuming it.
The two kinds of caller
The Shell distinguishes two completely separate authentication mechanisms. Picking the right one is the first thing you need to get right.
| Caller | Who it is | Credential | Used for |
|---|---|---|---|
| User | A human logged into your frontend | An Authentik OIDC JWT (Authorization: Bearer <jwt>) | Reading the catalog, managing identity/roles (admin UIs) |
| Service client | One of your backends | A machine secret (Authorization: Bearer <clientId>.<secret>) | Resolving permissions, reading the catalog server-side, admin automation |
A frontend authenticates as the logged-in user. A backend authenticates as itself (a service client) — never with a user's token. See User authentication and Service clients.
What you'll find here
- Architecture — how the pieces fit together.
- Permission model — the catalog hierarchy and the permission levels.
- Authentication — logging users in via Authentik, and authenticating your backend as a service client.
- The Catalog — declaring the apps, modules, and fields your application exposes.
- Resolving permissions — the one endpoint your backend calls on every request to find out what a user may do.
- API reference — every endpoint grouped by area and the auth it requires, linking to the live Swagger/OpenAPI UI the service serves for exact schemas.
- Enums & scopes and Errors — the canonical values and error shapes.
Base URL and versioning
The API is served behind a gateway path and is versioned in the URL (/v1). The host is
environment-specific — you will be given it. Throughout these docs we use a placeholder:
https://<your-shell-host>/api/shell/v1
Replace <your-shell-host> with the environment you were given. Every path in the
API reference is relative to this base.
Read Architecture and the Permission model first — the resolved-permissions payload will not make sense until you understand the catalog hierarchy.
Getting help
For questions about the Shell API or Authentik, or to report a problem, contact the team directly:
| Role | Contact |
|---|---|
| Engineering | david.stranava@koala42.com |
| Product | jakub.snorbert@koala42.com |