ores.iam.login_messages

Table of Contents

The login protocol messages.

1. Includes

#include <string>
#include <vector>

2. Messages

2.1. party_summary

2.1.1. id

2.1.2. name

2.1.3. party_category

2.1.4. business_center_code

2.2. database_info

/**
 * @brief The database row the deployment was built against.
 *
 * The four values =ores_database_info_tbl= records when the database is
 * created or recreated: the hash of the schema it was built from, the build
 * environment, the commit, and when the database was created. The table holds
 * exactly one row. It is declared by hand and owes nothing to the generators,
 * because it records the checkout that built the database before any service
 * runs.
 */

2.2.1. fingerprint

/** @brief The hash of the SQL scripts the database was built from. */

2.2.2. environment

/** @brief The build environment the database was built in. */

2.2.3. commit

/** @brief The git commit the database was built from. */

2.2.4. created

/** @brief When the database was created or recreated. */

2.3. login_request

2.3.1. principal

2.3.2. password

2.4. login_response

2.4.1. success

2.4.2. account_id

2.4.3. tenant_id

2.4.4. tenant_name

2.4.5. version

/**
 * @brief The build the answering service runs, in full.
 *
 * A session is a session with a deployment, so the answer that opens one
 * states which build it was opened against: a client that signs in states the
 * deployment's version without having asked whether the deployment still
 * needs an administrator, and a client that did ask can see whether the two
 * answers agree.
 */

2.4.6. database

/**
 * @brief The database the deployment stores into, in full.
 *
 * The row travels with the build the answer already states, because the two
 * answer one question — what am I talking to — and the database is its third.
 * Its audience is the build's audience: everyone who may open a session may
 * read it, so it needs no subject, no permission and no read of its own. The
 * iam service reads it once per login from =ores_database_info_tbl=.
 */

2.4.7. username

2.4.8. email

2.4.9. password_reset_required

2.4.10. tenant_bootstrap_mode

2.4.11. tenant_bootstrapping

/**
 * @brief Whether the caller's tenant is still being set up.
 *
 * This is the tenant's own lifecycle status, which reads @c bootstrapping
 * until the tenant's setup run marks it @c active. It is a fact about the
 * tenant row, so every party of the tenant reads it the same way, and it is
 * what a screen must hold a tenant administrator's setup on.
 *
 * It is stated beside @c tenant_bootstrap_mode rather than derived from it.
 * That flag is a setting under the tenant's system party, and the completing
 * step clears it as a warning rather than a condition: a tenant that is
 * already active can still report the flag as set, so the flag cannot answer
 * this question on its own.
 */

2.4.12. party_setup_required

2.4.13. party_setup_warning

/**
 * @brief Set when the party provisioner wizard has completed
 * (onboarding.party = true) but the party is still Inactive. The
 * client should show a message instead of re-launching the wizard.
 */

2.4.14. token

2.4.15. error_message

2.4.16. error_code

/**
 * @brief The stable code a client branches on.
 *
 * Empty when the sign-in succeeded. The message beside it is for a person
 * and may change; this is what a screen branches on, so a locked account is
 * distinguishable from a wrong password without matching English prose. The
 * codes a sign-in can answer with are collected on the Entry journeys page.
 */

2.4.17. message

2.4.18. selected_party_id

2.4.19. available_parties

2.4.20. default_party_id

/**
 * @brief The account's stored default party, if set and among
 * @c available_parties. Empty when unset. Only meaningful when
 * @c selected_party_id is empty (multi-party login, picker step).
 */

2.4.21. access_lifetime_s

/**
 * @brief Token lifetime in seconds as configured on the server.
 *
 * Clients use this to arm the proactive refresh timer so that the
 * timer interval tracks any server-side configuration changes.
 */

2.4.22. session_id

/**
 * @brief The IAM session UUID created for this login.
 *
 * Matches the session record in ores_iam_sessions_tbl. Clients should
 * forward this as Nats-Session-Id on every subsequent request so that
 * all calls from a single login session can be correlated in logs.
 */

2.5. logout_request

2.6. logout_response

2.6.1. success

2.6.2. message

2.7. public_key_request

2.8. refresh_request

/**
 * @brief Request to refresh a JWT token.
 *
 * The current token is passed in the Authorization: Bearer header.
 * No request body is needed — identity is taken from the token claims.
 */

2.9. refresh_response

/**
 * @brief Response to a token refresh request.
 */

2.9.1. success

2.9.2. token

2.9.3. message

2.9.4. access_lifetime_s

/**
 * @brief Token lifetime in seconds for the newly issued token.
 *
 * Clients re-arm the proactive refresh timer using this value.
 */

2.10. service_login_request

/**
 * @brief Authenticates a service account and issues a JWT.
 *
 * Service accounts cannot log in with the regular password-based login path.
 * They authenticate by presenting their database user password (which is
 * stored as a SHA-256 hash in the service account row). On success the IAM
 * service creates a session and returns a short-lived RS256 JWT identical in
 * structure to a human login token.
 *
 * The @p username must match the @c username column of an existing service
 * account (i.e. the database user name such as "ores_local1_reporting_service").
 * The @p password is the plaintext database password for that user.
 */

2.10.1. username

2.10.2. password

2.11. service_login_response

2.11.1. success

2.11.2. token

2.11.3. message

2.11.4. access_lifetime_s

Emacs 29.3 (Org mode 9.6.15)