Overview

last updated: 2025-09-10

DTZ Identity manages three things: Roles, Identities, and Authentications for every resource that lives inside a Context. Contexts are the organizational units in DTZ; every entity belongs to one, and access control flows through it.

Identity Entity Relationship Diagram

Core concepts

Context

A Context (context-…) is the container for your applications, services, and billing. The creator is auto-assigned Context Admin, and a service identity like admin@{context_id}.dtz.rocks is provisioned for automation.

Identities

An Identity is a principal (human user or service account). You’ll bind role assignments to identities.

Roles (Abstract vs. Concrete)

  • Abstract roles are reusable permission sets defined by each DTZ service (e.g., “containers admin”, “objectstore admin”, “billing admin”).
  • Concrete roles are abstract roles bound to a scope (either a Context or an Identity) and expressed as a role URI. These are what you actually assign.

Examples of concrete role URIs:

  • Context-scoped: https://dtz.rocks/containers/admin/{context_id}
  • Identity-scoped: https://dtz.rocks/identity/admin/{identity_id}

This split keeps permission logic consistent while making assignments context-aware.

Role scopes

Identity-scoped roles

Affect actions on the identity itself (e.g., who can set a password or create API keys for an identity).

Common examples:

  • https://dtz.rocks/identity/admin/{identity_id}
  • https://dtz.rocks/billing/admin/{identity_id}
  • https://dtz.rocks/identity/assume/{identity_id}

Context-scoped roles

Affect actions within a context (deployments, logs, object store, etc.).

Common examples:

  • https://dtz.rocks/context/admin/{context_id}
  • https://dtz.rocks/containers/admin/{context_id}
  • https://dtz.rocks/objectstore/admin/{context_id}
  • https://dtz.rocks/observability/admin/{context_id}
  • https://dtz.rocks/containerregistry/admin/{context_id}
  • https://dtz.rocks/rss2email/admin/{context_id}

Each DTZ service can define its own role names and scopes; the URIs above are representative.

How permissions are evaluated

  1. Authenticate (who you are).
  2. Resolve concrete roles for the caller (role URIs on the identity).
  3. Authorize based on whether a required role URI matches the target scope (context or identity) and action.

Example: assigning and using a role

  1. Assign the abstract “containers admin” to a specific context → you get a concrete role:

https://dtz.rocks/containers/admin/context-abc123

  1. Bind that role to the identity alice@example.com.
  2. When Alice calls the Containers API inside context-abc123, the role URI matches and the action is authorized. The same role does not grant rights in other contexts.

Authentication

DTZ supports multiple auth methods; use what fits your client and environment.

API Keys

  • Keys are created in the Identity UI and are scoped to a context and an identity.
  • Send via header:

X-API-KEY: YOUR_API_KEY

  • Some third-party integrations that can’t set headers can pass apiKey as a query parameter (use only when unavoidable).

Bearer tokens (password login)

Obtain a JWT by POSTing username/password, then send Authorization: Bearer ….

Request token:

POST https://identity.dtz.rocks/api/2021-02-21/token/auth
Content-Type: application/json

{
"username": "user",
"password": "password"
}

Use token:

curl -H "Authorization: Bearer eyJhb..." \
  https://identity.dtz.rocks/api/2021-02-21/me

You can also use the JWT as a cookie named dtz-auth. Basic auth is supported for some endpoints (apikey:apikey-1234).

Getting started checklist

  • Create or select a Context for your app.
  • Decide which abstract roles your app needs and bind them into concrete roles at the right scopes (Context vs. Identity).
  • Assign those concrete roles to the identities (users/service accounts) that need them.