C++ APISession methods

create_account

Creates a new application account for the current initialized session.

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 retry_after = 0s.

FieldPractical check
result.retry_afterresult.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++17 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;
}

Create-account statuses

ValueStatusReturned when
1okAccount was created successfully.
5too_many_requestsToo many no-license accounts were created from the same IP during the active limit window.
6internal_server_errorServer could not complete account creation because of an internal error.
100license_not_foundOptional credentials.license was not found in the current application.
101license_too_shortOptional credentials.license is shorter than 6 characters. This is rejected locally before the request is sent.
102license_too_longOptional credentials.license is longer than 64 characters. This is rejected locally before the request is sent.
106license_already_linkedOptional credentials.license is already linked to another account.
107license_already_activatedOptional credentials.license is already activated.
202app_user_already_existsAccount with the same identity already exists.
204app_user_requires_licenseApplication requires a license for account creation, but request did not provide a non-empty credentials.license.
205app_user_login_too_shortcredentials.login is shorter than 4 characters. This is rejected locally before the request is sent.
206app_user_login_too_longcredentials.login is longer than 320 characters. This is rejected locally before the request is sent.
207app_user_password_too_shortcredentials.password is shorter than 4 characters. This is rejected locally before the request is sent.
208app_user_password_too_longcredentials.password is longer than 64 characters. This is rejected locally before the request is sent.
209app_user_email_invalidcredentials.type is email_password, but credentials.login is not a valid email address.
210app_user_credentials_type_invalidcredentials.type has an unsupported value.
603app_accounts_quota_exceededApplication 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 codeMeaningWhen it can happen
4200not_initializedcreate_account was called before a successful initialize.
4201rate_limitedSession or IP rate limiting closed the websocket around this operation.

On this page