Identity Apps overview — Cliodot Documentation

Product ability: Identity Apps give services a real identity so they can authenticate as themselves, earn trust, and call Capabilities and Surfaces with short-lived credentials — including cross-tenant — instead of pasting permanent API keys between teams.

Continue with Authenticate and tokens for provider(), scopes, and the token cache.

Identity Apps turn software applications into first-class identities on Cliodot — the same way users are identities — so services and apps authenticate as themselves, establish trust, and call what they are allowed to call.

Service-to-service authentication is a primary use of Identity Apps. Identity is the identity and trust foundation for those calls — not a place where services merely store API keys.

Order Service
     │
     │ authenticate as
     ▼
Orders Identity
     │
     │ trusted to call
     ▼
Payment App

Payment can establish: this request is from the Orders identity, and that identity is allowed to call me.

The problem Identity solves#

Without Identity, integrations usually mean:

orders-service      → PAYMENT_API_KEY
inventory-service   → PAYMENT_API_KEY
notification-service → PAYMENT_API_KEY

Payment only asks “does this request have the correct secret?” — not which service is calling.

With Identity:

                    Identity
                         │
       ┌─────────────────┼─────────────────┐
       │                 │                 │
       ▼                 ▼                 ▼
 Orders Identity   Inventory Identity   Notification Identity
       │
       │ authenticated request
       ▼
 Payment App

Payment can resolve caller identity, tenant, environment, permission, and trust — instead of a bare shared secret.

Identity replaces the credential-first loop (generate, paste, rotate, hope) with application identity and approved relationships.

Authentication vs authorization#

Question	Meaning	Example
Authentication	Who are you?	`orders-service` as `identity_orders`
Authorization	Are you allowed to do this?	`payments.create` allowed

Identity owns the relationship chain:

Service → Identity → Authentication → Trust → Permission → Application → Action

Or in product language:

WHO ARE YOU?          → Identity
CAN I TRUST YOU?      → Trust
WHAT CAN YOU DO?      → Permission / scopes
WHAT ARE YOU CALLING? → Application (Surface, Capability, Event App, …)
                      → Action

How trust works#

Register the calling application as an Identity App in the portal.
Publish the capability or Surface the other side exposes.
Request access from the consuming app.
Approve with permissions, expiry, quotas, environment limits, or conditions.
Trust is established — no shared secret is emailed around.
Consume at runtime with the SDK; Cliodot resolves identity, trust, and tokens.

Applications request access to business capabilities (aligned with Surfaces) — for example Employee.Create or payments.create — not only raw HTTP endpoints.

External systems that still need API keys, OAuth, or certificates can keep those under the hood. Application Identity is the platform abstraction; Cliodot can manage those lower-level credentials so developers do not.

Surfaces can become identity-aware: besides API keys or JWTs, a Surface can allow only trusted applications.

Short-lived credentials, not permanent shared keys#

Avoid:

service → permanent API key pasted everywhere

Prefer:

orders-service → authenticate → Identity → short-lived credential → Payment App

The issued access token represents the caller’s identity for a target audience — tenant, permissions, and trust included — so the callee validates who is calling, not only that someone holds a secret.

Cross-tenant service authentication#

Identity is especially useful across tenants.

Tenant A — Order Service / Orders Identity
        │
        │ trusted
        ▼
Tenant B — Payment App

Tenant B explicitly trusts Tenant A’s identity. The service authenticates as itself; Tenant B decides trust. The caller does not need Tenant B’s secret.

Same-tenant direct trust and cross-tenant trust invites are configured in the portal; the SDK authenticates and verifies against that trust.

One governing Identity per application#

An application is typically governed by one Identity App, which then covers the product surface around it — Event Apps, Webhook Apps, Surfaces, and other Cliodot products that designate that Identity as their Identity Provider.

Orders App
   └── governed by Orders Identity
          ├── Event App
          ├── Payment / Surface
          ├── Webhook App
          └── …

The service’s identity is not recreated for every capability.

After a product links an Identity Provider: callers keep the product appId / Surface slug, but present an Identity iak_ or secret (product *ak_ / secrets stop working for those runtime calls).

What an Identity App carries#

An Identity App is a registered application identity owned by an organization and environment. It carries:

who the app is
organization and environment
trust relationships
permissions / scopes
audit history
policies

Positioning:

Cliodot Identity provides application identity, service-to-service authentication, trust relationships, authorization, credential management, and controlled access to Cliodot capabilities and external identities.

Portal vs SDK#

In the portal	In the SDK
Create Identity Apps	Authenticate as an app
Trust allowlists / invites	Verify access tokens
Token policy, keys, scopes	Refresh / revoke
Pipelines and governance	Offline verify helpers, token cache

Runtime client lives in the cliodot package. Base path: /identity. Auth: x-cliodot-app-id + Bearer iak_…, or app secret.

App ids are memorable strings you choose at create time (for example identity_hrms, identity_orders). Secrets and iak_ keys stay complex.