authorize(credentials)

authorize(account_credentials credentials) authenticates the current initialized session with application account credentials and returns the public blaze::account result object.

Function variants

blaze::account authorize(blaze::account_credentials credentials);
blaze::account authorize(blaze::account_credentials credentials, std::error_code& ec) noexcept;
void async_authorize(
  blaze::account_credentials credentials,
  std::function<void(std::error_code, blaze::account)> callback
);
blaze::coro::awaitable_result<blaze::account> co_authorize(blaze::account_credentials credentials);

Status vs error

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

Result

struct account {
  std::string login;
  std::vector<std::string> levels;
  std::string comment;
  std::string ip_address;
  std::chrono::seconds time_left{};
  bool license_required{};
  blaze::status status{};

  bool good() const noexcept;
  bool already_authorized() const noexcept;
};

Prop

Type

account.good() is equivalent to status == blaze::status::ok.

Field	Practical check
`account.login`	`account.login.empty()`
`account.levels`	`account.levels.empty()`
`account.comment`	`account.comment.empty()`
`account.ip_address`	`account.ip_address.empty()`
`account.time_left`	`account.time_left.count() == 0`

account.license_required == false is not a reliable presence check. In the current library this field defaults to false when it is omitted, so interpret it primarily when account.status == blaze::status::ok.

Behavior notes

Call authorize 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.
credentials.comment is not transmitted by this overload.
If credentials.type == blaze::credentials_type::email_password, the server expects credentials.login to be a valid email address.
app_user_not_found is used both for an unknown account and for invalid credentials.
If the server omits levels, comment, ip_address, time_left, or license_required, the library returns default values instead of std::optional, because it targets C++14 compatibility.

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 optional_license = read_line("License (optional, leave empty to skip)");

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

  blaze::session session;

  try {
    session.connect();

    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::account account = session.authorize(credentials);
    if (!account.good()) {
      print_status("Authorize returned status", account.status);
      return 1;
    }

    std::cout << "Authorized account login: " << account.login << '\n';
    std::cout << "Levels count: " << account.levels.size() << '\n';
    std::cout << "Comment: " << (account.comment.empty() ? "<empty>" : account.comment) << '\n';
    std::cout << "IP address: " << (account.ip_address.empty() ? "<empty>" : account.ip_address) << '\n';
    std::cout << "License required: " << (account.license_required ? "true" : "false") << '\n';
    std::cout << "Time left/raw time value: " << account.time_left.count() << '\n';

    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Authorize 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 optional_license = read_line("License (optional, leave empty to skip)");

  blaze::account_credentials credentials;
  credentials.login = login;
  credentials.password = password;
  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) mutable {
      if (connect_ec) {
        print_error_code("Connect failed", connect_ec);
        completion.set_value(1);
        return;
      }

      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_authorize(std::move(credentials),
            [&session, &completion](std::error_code auth_ec, blaze::account account) {
              if (auth_ec) {
                print_error_code("Authorize failed", auth_ec);
                completion.set_value(1);
                return;
              }

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

              std::cout << "Authorized account login: " << account.login << '\n';
              std::cout << "Levels count: " << account.levels.size() << '\n';
              std::cout << "Comment: " << (account.comment.empty() ? "<empty>" : account.comment) << '\n';
              std::cout << "IP address: " << (account.ip_address.empty() ? "<empty>" : account.ip_address) << '\n';
              std::cout << "License required: " << (account.license_required ? "true" : "false") << '\n';
              std::cout << "Time left/raw time value: " << account.time_left.count() << '\n';

              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;
  }

  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 [auth_ec, account] = co_await session.co_authorize(std::move(credentials));
  if (auth_ec) {
    co_return auth_ec;
  }

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

  std::cout << "Authorized account login: " << account.login << '\n';
  std::cout << "Levels count: " << account.levels.size() << '\n';
  std::cout << "Comment: " << (account.comment.empty() ? "<empty>" : account.comment) << '\n';
  std::cout << "IP address: " << (account.ip_address.empty() ? "<empty>" : account.ip_address) << '\n';
  std::cout << "License required: " << (account.license_required ? "true" : "false") << '\n';
  std::cout << "Time left/raw time value: " << account.time_left.count() << '\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 optional_license = read_line("License (optional, leave empty to skip)");

  blaze::account_credentials credentials;
  credentials.login = login;
  credentials.password = password;
  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("Authorize 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

Authorize statuses

Value	Status	Returned when
`1`	`ok`	Credentials authorization succeeded.
`6`	`internal_server_error`	Server could not complete account authorization because of an internal error.
`7`	`already_authorized`	Current session is already authorized.
`100`	`license_not_found`	Optional `credentials.license` does not exist 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.
`107`	`license_already_activated`	Optional `credentials.license` is already activated.
`200`	`app_user_not_found`	Account does not exist or provided credentials are invalid.
`201`	`app_user_blacklisted`	Account exists but is blacklisted.
`203`	`app_user_has_no_valid_licenses`	Account requires license coverage, but no valid active coverage is available.
`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.
`502`	`client_id_mismatch`	Account is already bound to another client identifier.
`602`	`app_sessions_quota_exceeded`	Application authorized session quota was reached.

Connection-level shutdowns

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

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