API docs by Redocly

ACMEbase — Platform API (auth, users, providers) + shared components (0.3.0)

Download OpenAPI specification:

License: Apache-2.0

Foundation of the ACMEsuite (ACMEbase). Two roles in one spec:

  1. Platform API — authentication (local login + federated provider options), the current user, self-service password, and the admin surface (user/role management + federated auth-provider configuration). Identity may be local or federated (Entra/OIDC), but the access role is always assigned locally in Base. After a successful login Base issues its own session JWT (bearer); the module APIs validate that token only and never see the external IdP.

  2. Shared components — value types (Money, DateRange), the RFC-7807 error object, the generic error responses, the e-approval types (Approval/ApprovalDecision) and the auth scheme. The four module specs (hr/crm/build/supply) reference these via cross-file $ref (acme-base.yaml#/components/...); redocly bundle resolves them when needed.

Roles (ACMEbase auth): WATCH reads · WORK writes operationally · ADMIN maintains master data and administers the platform; hierarchy ADMIN > WORK > WATCH. Annotated per operation as x-required-role. Note: because of OpenAPI 3.0, the bearerAuth scheme must additionally be declared locally in each module spec (a security requirement cannot be resolved via cross-file $ref); the definition maintained here is the canonical template.

Auth

Sign-in, current user, self-service password.

Sign in with local credentials

Request Body schema: application/json
required
username
required
string
password
required
string <password>

Responses

Response Schema: application/json
token
string

Base session JWT (bearer).

mustSetPassword
boolean

If true

object (SessionUser)

The signed-in user (also the subject of the session token).

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "mustSetPassword": true,
  • "user": {
    • "id": "string",
    • "username": "string",
    • "email": "string",
    • "displayName": "string",
    • "role": "WATCH",
    • "status": "ACTIVE",
    • "auditor": true
    }
}

List sign-in options

Responses

Response Schema: application/json
Array
id
string
displayName
string
kind
string (ProviderKind)
Enum: "LOCAL" "OIDC"

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "displayName": "string",
    • "kind": "LOCAL"
    }
]

Current user

Authorizations:
bearerAuth

Responses

Response Schema: application/json
id
string
username
string or null
email
string or null
displayName
string or null
role
string (AccessRole)
Enum: "WATCH" "WORK" "ADMIN"

Access role; hierarchy ADMIN > WORK > WATCH.

status
string (UserStatus)
Enum: "ACTIVE" "PENDING" "DISABLED"

ACTIVE may sign in · PENDING awaits role assignment · DISABLED is blocked.

auditor
boolean

Orthogonal AUDIT capability (ADR-0010): may view version history. Independent of the access role; granted separately by an admin.

Response samples

Content type
application/json
{
  • "id": "string",
  • "username": "string",
  • "email": "string",
  • "displayName": "string",
  • "role": "WATCH",
  • "status": "ACTIVE",
  • "auditor": true
}

Set or rotate own password

Authorizations:
bearerAuth
Request Body schema: application/json
required
newPassword
required
string <password> >= 10 characters

Responses

Request samples

Content type
application/json
{
  • "newPassword": "pa$$word_q"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string"
}

Whether the self-claim screen should replace the normal login form

True only when acme.base.auth.bootstrap.allow-self-claim is enabled server-side AND no admin exists yet. Only ever enabled on instances not reachable by untrusted parties before the real operator claims the account (e.g. local development) — never in a public deployment.

Responses

Response Schema: application/json
needsSetup
boolean

Show the self-claim screen instead of the normal login form.

Response samples

Content type
application/json
{
  • "needsSetup": true
}

Claim the initial admin account with an operator-chosen password

Only reachable while bootstrap-status reports needsSetup: true; 404s otherwise (same response whether the feature is disabled or already claimed, so it never leaks state to an unauthenticated caller). No forced password change — the operator chose it deliberately.

Request Body schema: application/json
required
username
string

Defaults to the configured bootstrap admin username (usually "admin") if omitted.

password
required
string <password> >= 10 characters

Responses

Response Schema: application/json
token
string

Base session JWT (bearer).

mustSetPassword
boolean

If true

object (SessionUser)

The signed-in user (also the subject of the session token).

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "pa$$word_q"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "mustSetPassword": true,
  • "user": {
    • "id": "string",
    • "username": "string",
    • "email": "string",
    • "displayName": "string",
    • "role": "WATCH",
    • "status": "ACTIVE",
    • "auditor": true
    }
}

Users

User & role administration (ADMIN).

List users

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array
id
string
username
string or null
email
string or null
displayName
string or null
role
string (AccessRole)
Enum: "WATCH" "WORK" "ADMIN"

Access role; hierarchy ADMIN > WORK > WATCH.

status
string (UserStatus)
Enum: "ACTIVE" "PENDING" "DISABLED"

ACTIVE may sign in · PENDING awaits role assignment · DISABLED is blocked.

auditor
boolean

Orthogonal AUDIT capability (ADR-0010): may view version history. Independent of the access role; granted separately by an admin.

authProvider
string

'local' or a configured provider id.

updatedAt
string or null <date-time>

When the record was last changed.

updatedBy
string or null

Who last changed the record.

Response samples

Content type
application/json
[
  • {
    • "id": "string",
    • "username": "string",
    • "email": "string",
    • "displayName": "string",
    • "role": "WATCH",
    • "status": "ACTIVE",
    • "auditor": true,
    • "authProvider": "string",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "updatedBy": "string"
    }
]

Create a local user

Authorizations:
bearerAuth
Request Body schema: application/json
required
username
required
string
displayName
string
email
string
role
required
string (AccessRole)
Enum: "WATCH" "WORK" "ADMIN"

Access role; hierarchy ADMIN > WORK > WATCH.

Responses

Response Schema: application/json
object (DirectoryUser)

A user in the admin directory (adds the authenticating provider and the last-change stamp). Who/when of the last change is visible to everyone (ADR-0010); the version number is not.

temporaryPassword
string

One-time password; shown once

Request samples

Content type
application/json
{
  • "username": "string",
  • "displayName": "string",
  • "email": "string",
  • "role": "WATCH"
}

Response samples

Content type
application/json
{
  • "user": {
    • "id": "string",
    • "username": "string",
    • "email": "string",
    • "displayName": "string",
    • "role": "WATCH",
    • "status": "ACTIVE",
    • "auditor": true,
    • "authProvider": "string",
    • "updatedAt": "2019-08-24T14:15:22Z",
    • "updatedBy": "string"
    },
  • "temporaryPassword": "string"
}

Set a user's access role

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
role
required
string (AccessRole)
Enum: "WATCH" "WORK" "ADMIN"

Access role; hierarchy ADMIN > WORK > WATCH.

Responses

Response Schema: application/json
id
string
username
string or null
email
string or null
displayName
string or null
role
string (AccessRole)
Enum: "WATCH" "WORK" "ADMIN"

Access role; hierarchy ADMIN > WORK > WATCH.

status
string (UserStatus)
Enum: "ACTIVE" "PENDING" "DISABLED"

ACTIVE may sign in · PENDING awaits role assignment · DISABLED is blocked.

auditor
boolean

Orthogonal AUDIT capability (ADR-0010): may view version history. Independent of the access role; granted separately by an admin.

authProvider
string

'local' or a configured provider id.

updatedAt
string or null <date-time>

When the record was last changed.

updatedBy
string or null

Who last changed the record.

Request samples

Content type
application/json
{
  • "role": "WATCH"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "username": "string",
  • "email": "string",
  • "displayName": "string",
  • "role": "WATCH",
  • "status": "ACTIVE",
  • "auditor": true,
  • "authProvider": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string"
}

Set a user's status

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
status
required
string (UserStatus)
Enum: "ACTIVE" "PENDING" "DISABLED"

ACTIVE may sign in · PENDING awaits role assignment · DISABLED is blocked.

Responses

Response Schema: application/json
id
string
username
string or null
email
string or null
displayName
string or null
role
string (AccessRole)
Enum: "WATCH" "WORK" "ADMIN"

Access role; hierarchy ADMIN > WORK > WATCH.

status
string (UserStatus)
Enum: "ACTIVE" "PENDING" "DISABLED"

ACTIVE may sign in · PENDING awaits role assignment · DISABLED is blocked.

auditor
boolean

Orthogonal AUDIT capability (ADR-0010): may view version history. Independent of the access role; granted separately by an admin.

authProvider
string

'local' or a configured provider id.

updatedAt
string or null <date-time>

When the record was last changed.

updatedBy
string or null

Who last changed the record.

Request samples

Content type
application/json
{
  • "status": "ACTIVE"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "username": "string",
  • "email": "string",
  • "displayName": "string",
  • "role": "WATCH",
  • "status": "ACTIVE",
  • "auditor": true,
  • "authProvider": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string"
}

Grant or revoke the AUDIT capability

Orthogonal to the access role (ADR-0010) — may view version history.

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
auditor
required
boolean

Responses

Response Schema: application/json
id
string
username
string or null
email
string or null
displayName
string or null
role
string (AccessRole)
Enum: "WATCH" "WORK" "ADMIN"

Access role; hierarchy ADMIN > WORK > WATCH.

status
string (UserStatus)
Enum: "ACTIVE" "PENDING" "DISABLED"

ACTIVE may sign in · PENDING awaits role assignment · DISABLED is blocked.

auditor
boolean

Orthogonal AUDIT capability (ADR-0010): may view version history. Independent of the access role; granted separately by an admin.

authProvider
string

'local' or a configured provider id.

updatedAt
string or null <date-time>

When the record was last changed.

updatedBy
string or null

Who last changed the record.

Request samples

Content type
application/json
{
  • "auditor": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "username": "string",
  • "email": "string",
  • "displayName": "string",
  • "role": "WATCH",
  • "status": "ACTIVE",
  • "auditor": true,
  • "authProvider": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string"
}

Version history of a user

Full versioned change history (ADR-0010). Requires the AUDIT capability — ordinary users, including ADMINs without AUDIT, cannot see version numbers or earlier versions.

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response Schema: application/json
Array
revision
integer <int64>

Monotonic version number.

changedAt
string <date-time>
changedBy
string or null
changeType
string (RevisionType)
Enum: "ADD" "MOD" "DEL"

How the record changed at this revision (add / modify / delete-tombstone).

username
string or null
email
string or null
displayName
string or null
role
string (AccessRole)
Enum: "WATCH" "WORK" "ADMIN"

Access role; hierarchy ADMIN > WORK > WATCH.

status
string (UserStatus)
Enum: "ACTIVE" "PENDING" "DISABLED"

ACTIVE may sign in · PENDING awaits role assignment · DISABLED is blocked.

auditor
boolean
deleted
boolean

Whether this revision is a tombstone.

Response samples

Content type
application/json
[
  • {
    • "revision": 0,
    • "changedAt": "2019-08-24T14:15:22Z",
    • "changedBy": "string",
    • "changeType": "ADD",
    • "username": "string",
    • "email": "string",
    • "displayName": "string",
    • "role": "WATCH",
    • "status": "ACTIVE",
    • "auditor": true,
    • "deleted": true
    }
]

Providers

Federated identity-provider configuration (ADMIN).

List federated provider configurations

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array
providerId
string
displayName
string
kind
string (ProviderKind)
Enum: "LOCAL" "OIDC"
enabled
boolean
configured
boolean
Array of objects (ProviderField)
object

Non-secret field values.

secretsSet
Array of strings

Keys of secret fields that currently have a stored value.

Response samples

Content type
application/json
[
  • {
    • "providerId": "string",
    • "displayName": "string",
    • "kind": "LOCAL",
    • "enabled": true,
    • "configured": true,
    • "schema": [
      ],
    • "values": {
      },
    • "secretsSet": [
      ]
    }
]

Create or update a provider configuration

Authorizations:
bearerAuth
path Parameters
providerId
required
string
Request Body schema: application/json
required
enabled
boolean
object

Field values; a blank secret keeps the stored one.

Responses

Response Schema: application/json
providerId
string
displayName
string
kind
string (ProviderKind)
Enum: "LOCAL" "OIDC"
enabled
boolean
configured
boolean
Array of objects (ProviderField)
object

Non-secret field values.

secretsSet
Array of strings

Keys of secret fields that currently have a stored value.

Request samples

Content type
application/json
{
  • "enabled": true,
  • "values": {
    • "property1": "string",
    • "property2": "string"
    }
}

Response samples

Content type
application/json
{
  • "providerId": "string",
  • "displayName": "string",
  • "kind": "LOCAL",
  • "enabled": true,
  • "configured": true,
  • "schema": [
    • {
      }
    ],
  • "values": {
    • "property1": "string",
    • "property2": "string"
    },
  • "secretsSet": [
    • "string"
    ]
}

Remove a provider configuration

Authorizations:
bearerAuth
path Parameters
providerId
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string"
}