create_account

create_account(account_credentials credentials) creates a new application account inside the current initialized application and returns blaze::retryable_status.

Function variants

blaze::retryable_status create_account(blaze::account_credentials credentials);
blaze::retryable_status create_account(blaze::account_credentials credentials, std::error_code& ec) noexcept;
void async_create_account(
  blaze::account_credentials credentials,
  std::function<void(std::error_code, blaze::retryable_status)> callback
);
blaze::coro::awaitable_result<blaze::retryable_status> co_create_account(blaze::account_credentials credentials);

Status vs error

retryable_status.status is the API result. std::error_code and std::system_error are used for transport/runtime failures only.

Parameters

struct account_credentials {
  std::string login;
  std::string password;
  std::string comment;
  std::string license;
  blaze::credentials_type type{blaze::credentials_type::login_password};
};

Prop

Type

Result

struct retryable_status {
  blaze::status status;
  std::chrono::seconds retry_after;

  bool operator==(blaze::status status) const noexcept;
  bool operator!=(blaze::status status) const noexcept;
};

Prop

Type

Status comparison

blaze::retryable_status supports direct comparison with blaze::status through both == and !=.

Checking returned fields

If the server omits retry metadata, the library returns a default value instead of std::optional, because it targets C++14 compatibility.

Field	Practical check
`result.retry_after`	`result.retry_after.count() == 0`

Behavior notes

Call create_account only after successful connect and initialize.
Login and password length are validated locally before the request is sent.
If credentials.license is provided, its length is also validated locally before the request is sent.
If credentials.comment is empty, the field is omitted from the request.
If credentials.license is empty, the field is omitted from the request.
If credentials.type == blaze::credentials_type::email_password, the server expects credentials.login to be a valid email address.
Per-IP create-account limiting applies only to account creation without a linked license.
If account creation succeeds with a non-empty credentials.license, the server links and activates that license for the new account.

Example

Compilation note

Synchronous and Asynchronous examples compile in the same form from C++14 to C++26.

#include "blazeauth/api/api.hpp"

#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

std::string read_line(const std::string& label) {
  std::string value;
  std::cout << label << ": ";
  std::getline(std::cin, value);
  return value;
}

void print_status(const std::string& context, blaze::status status) {
  std::cout << context << ": "
            << static_cast<unsigned int>(status)
            << " (" << blaze::to_string(status) << ")\n";
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");
  const std::string login = read_line("Login");
  const std::string password = read_line("Password");
  const std::string comment = read_line("Comment (optional)");
  const std::string optional_license = read_line("License (optional, leave empty to skip)");

  blaze::account_credentials credentials;
  credentials.login = login;
  credentials.password = password;
  credentials.comment = comment;
  credentials.type = blaze::credentials_type::login_password;
  if (!optional_license.empty()) {
    credentials.license = optional_license;
  }

  blaze::session session;

  try {
    const blaze::api_server server = session.connect();
    std::cout << "Connected to server location: " << server.location << '\n';

    const blaze::application app = session.initialize(websocket_api_key, client_id);
    if (!app.good()) {
      print_status("Initialize returned status", app.status);
      return 1;
    }

    const blaze::retryable_status result = session.create_account(credentials);
    if (result == blaze::status::ok) {
      std::cout << "Account created successfully\n";
    } else if (result == blaze::status::too_many_requests) {
      print_status("Create-account returned status", result.status);
      if (result.retry_after.count() != 0) {
        std::cout << "Retry after: " << result.retry_after.count() << " seconds\n";
      }
      return 1;
    } else {
      print_status("Create-account returned status", result.status);
      return 1;
    }

    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Create-account failed", e.code());
    return 1;
  }

  return 0;
}

#include "blazeauth/api/api.hpp"

#include <future>
#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

std::string read_line(const std::string& label) {
  std::string value;
  std::cout << label << ": ";
  std::getline(std::cin, value);
  return value;
}

void print_status(const std::string& context, blaze::status status) {
  std::cout << context << ": "
            << static_cast<unsigned int>(status)
            << " (" << blaze::to_string(status) << ")\n";
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");
  const std::string login = read_line("Login");
  const std::string password = read_line("Password");
  const std::string comment = read_line("Comment (optional)");
  const std::string optional_license = read_line("License (optional, leave empty to skip)");

  blaze::account_credentials credentials;
  credentials.login = login;
  credentials.password = password;
  credentials.comment = comment;
  credentials.type = blaze::credentials_type::login_password;
  if (!optional_license.empty()) {
    credentials.license = optional_license;
  }

  blaze::session session;

  std::promise<int> completion;
  std::future<int> result = completion.get_future();

  session.async_connect(
    [&session, &completion, websocket_api_key, client_id, credentials](std::error_code connect_ec, blaze::api_server server) mutable {
      if (connect_ec) {
        print_error_code("Connect failed", connect_ec);
        completion.set_value(1);
        return;
      }

      std::cout << "Connected to server location: " << server.location << '\n';

      session.async_initialize(websocket_api_key, client_id,
        [&session, &completion, credentials](std::error_code init_ec, blaze::application app) mutable {
          if (init_ec) {
            print_error_code("Initialize failed", init_ec);
            completion.set_value(1);
            return;
          }

          if (!app.good()) {
            print_status("Initialize returned status", app.status);
            completion.set_value(1);
            return;
          }

          session.async_create_account(std::move(credentials),
            [&session, &completion](std::error_code create_ec, blaze::retryable_status result) {
              if (create_ec) {
                print_error_code("Create-account failed", create_ec);
                completion.set_value(1);
                return;
              }

              if (result == blaze::status::ok) {
                std::cout << "Account created successfully\n";
              } else {
                print_status("Create-account returned status", result.status);
                if (result == blaze::status::too_many_requests && result.retry_after.count() != 0) {
                  std::cout << "Retry after: " << result.retry_after.count() << " seconds\n";
                }
                completion.set_value(1);
                return;
              }

              session.async_shutdown([&completion](std::error_code shutdown_ec) {
                if (shutdown_ec) {
                  print_error_code("Shutdown failed", shutdown_ec);
                  completion.set_value(1);
                  return;
                }

                completion.set_value(0);
              });
            });
        });
    });

  return result.get();
}

Project must be built with C++20 support and with coroutine support available both in the language mode and in the standard library implementation for this example to compile correctly.

#include "blazeauth/api/api.hpp"

#include <future>
#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

std::string read_line(const std::string& label) {
  std::string value;
  std::cout << label << ": ";
  std::getline(std::cin, value);
  return value;
}

#if BLAZEAUTH_HAS_COROUTINES

blaze::coro::task<std::error_code> run_example(
  blaze::session& session,
  const std::string& websocket_api_key,
  const std::string& client_id,
  blaze::account_credentials credentials
) {
  const auto [connect_ec, server] = co_await session.co_connect();
  if (connect_ec) {
    co_return connect_ec;
  }

  std::cout << "Connected to server location: " << server.location << '\n';

  const auto [init_ec, app] = co_await session.co_initialize(websocket_api_key, client_id);
  if (init_ec) {
    co_return init_ec;
  }

  if (!app.good()) {
    co_return blaze::make_error_code(app.status);
  }

  const auto [create_ec, result] = co_await session.co_create_account(std::move(credentials));
  if (create_ec) {
    co_return create_ec;
  }

  if (result != blaze::status::ok) {
    if (result == blaze::status::too_many_requests && result.retry_after.count() != 0) {
      std::cout << "Retry after: " << result.retry_after.count() << " seconds\n";
    }
    co_return blaze::make_error_code(result.status);
  }

  std::cout << "Account created successfully\n";

  const auto [shutdown_ec] = co_await session.co_shutdown();
  co_return shutdown_ec;
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");
  const std::string login = read_line("Login");
  const std::string password = read_line("Password");
  const std::string comment = read_line("Comment (optional)");
  const std::string optional_license = read_line("License (optional, leave empty to skip)");

  blaze::account_credentials credentials;
  credentials.login = login;
  credentials.password = password;
  credentials.comment = comment;
  credentials.type = blaze::credentials_type::login_password;
  if (!optional_license.empty()) {
    credentials.license = optional_license;
  }

  blaze::session session;

  std::promise<std::error_code> completion;
  std::future<std::error_code> result = completion.get_future();

  blaze::coro::co_spawn(
    [&session, &completion, websocket_api_key, client_id, credentials = std::move(credentials)]() mutable
      -> blaze::coro::task<void> {
      const std::error_code ec =
        co_await run_example(session, websocket_api_key, client_id, std::move(credentials));
      completion.set_value(ec);
      co_return;
    }());

  const std::error_code ec = result.get();
  if (ec) {
    print_error_code("Create-account failed", ec);
    return 1;
  }

  return 0;
}

#else

int main() {
  std::cout << "This example requires coroutine support in the Blazeauth library build.\n";
  return 0;
}

#endif

Create-account statuses

Value	Status	Returned when
`1`	`ok`	Account was created successfully.
`5`	`too_many_requests`	Too many no-license accounts were created from the same IP during the active limit window.
`6`	`internal_server_error`	Server could not complete account creation because of an internal error.
`100`	`license_not_found`	Optional `credentials.license` was not found in the current application.
`101`	`license_too_short`	Optional `credentials.license` is shorter than 6 characters. This is rejected locally before the request is sent.
`102`	`license_too_long`	Optional `credentials.license` is longer than 64 characters. This is rejected locally before the request is sent.
`106`	`license_already_linked`	Optional `credentials.license` is already linked to another account.
`107`	`license_already_activated`	Optional `credentials.license` is already activated.
`202`	`app_user_already_exists`	Account with the same identity already exists.
`204`	`app_user_requires_license`	Application requires a license for account creation, but request did not provide a non-empty `credentials.license`.
`205`	`app_user_login_too_short`	`credentials.login` is shorter than 4 characters. This is rejected locally before the request is sent.
`206`	`app_user_login_too_long`	`credentials.login` is longer than 320 characters. This is rejected locally before the request is sent.
`207`	`app_user_password_too_short`	`credentials.password` is shorter than 4 characters. This is rejected locally before the request is sent.
`208`	`app_user_password_too_long`	`credentials.password` is longer than 64 characters. This is rejected locally before the request is sent.
`209`	`app_user_email_invalid`	`credentials.type` is `email_password`, but `credentials.login` is not a valid email address.
`210`	`app_user_credentials_type_invalid`	`credentials.type` has an unsupported value.
`603`	`app_accounts_quota_exceeded`	Application account quota was reached.

Connection-level shutdowns

Normal create-account results are returned in result.status. The websocket may still be closed by session-level guards:

Close code	Meaning	When it can happen
`4200`	`not_initialized`	`create_account` was called before a successful `initialize`.
`4201`	`rate_limited`	Session or IP rate limiting closed the websocket around this operation.

create_account

On this page