C++ APISession methods

authorize(credentials)

Authorizes the current initialized session using account 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.

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 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.

Checking returned fields

Missing fields are returned as default values. If account.status != blaze::status::ok, treat metadata fields as optional in practice and check them explicitly.

FieldPractical check
account.loginaccount.login.empty()
account.levelsaccount.levels.empty()
account.commentaccount.comment.empty()
account.ip_addressaccount.ip_address.empty()
account.time_leftaccount.time_left.count() == 0

About license_required

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.

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

Authorize statuses

ValueStatusReturned when
1okCredentials authorization succeeded.
6internal_server_errorServer could not complete account authorization because of an internal error.
7already_authorizedCurrent session is already authorized.
100license_not_foundOptional credentials.license does not exist 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.
107license_already_activatedOptional credentials.license is already activated.
200app_user_not_foundAccount does not exist or provided credentials are invalid.
201app_user_blacklistedAccount exists but is blacklisted.
203app_user_has_no_valid_licensesAccount requires license coverage, but no valid active coverage is available.
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.
502client_id_mismatchAccount is already bound to another client identifier.
602app_sessions_quota_exceededApplication 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 codeMeaningWhen it can happen
4200not_initializedauthorize was called before a successful initialize.
4201rate_limitedSession or IP rate limiting closed the websocket around this operation.

On this page