C++ APISession methods

initialize

Initializes a connected session with application context and client identity.

initialize binds the current connected session to your application and client. Until initialization succeeds, the rest of the API should be treated as unavailable.

Function variants

blaze::application initialize(std::string websocket_api_key, std::string client_id);
blaze::application initialize(std::string websocket_api_key, std::string client_id, std::error_code& ec) noexcept;
void async_initialize(
  std::string websocket_api_key,
  std::string client_id,
  std::function<void(std::error_code, blaze::application)> callback
);
blaze::coro::awaitable_result<blaze::application> co_initialize(
  std::string websocket_api_key,
  std::string client_id
);

Initialization timeout

After a new connection is opened, the session must be initialized within 15 seconds. Otherwise, the server closes the websocket with close code 4202.

Status vs error

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

Parameters

Prop

Type

Result

struct application {
  std::string name;
  std::string version;
  blaze::status status;

  bool good() const noexcept;
};

Prop

Type

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

Checking returned fields

When application.status != blaze::status::ok, metadata fields should be treated as not filled.

FieldPractical check
application.nameapplication.name.empty()
application.versionapplication.version.empty()

Behavior notes

  • Call initialize only after a successful connect.
  • The library sends the protocol version automatically. You provide only websocket_api_key and client_id.
  • client_id length is validated locally before the request is sent.
  • If status != blaze::status::ok, name and version are empty strings.
  • Coroutine overloads are available only when the library is built with coroutine support.

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

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");

  blaze::session session;

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

    // Transport/runtime failures throw std::system_error.
    const blaze::application app = session.initialize(websocket_api_key, client_id);

    // API-level result is returned in app.status.
    if (!app.good()) {
      std::cout << "Initialize returned status "
                << static_cast<unsigned int>(app.status)
                << " (" << blaze::to_string(app.status) << ")\n";
      return 1;
    }

    std::cout << "Application name: " << app.name << '\n';
    std::cout << "Application version: " << app.version << '\n';

    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Initialize 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;
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");

  blaze::session session;

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

  session.async_connect(
    [&session, &completion, websocket_api_key, client_id](std::error_code connect_ec, blaze::api_server server) {
      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](std::error_code init_ec, blaze::application app) {
          if (init_ec) {
            print_error_code("Initialize failed", init_ec);
            completion.set_value(1);
            return;
          }

          if (!app.good()) {
            std::cout << "Initialize returned status "
                      << static_cast<unsigned int>(app.status)
                      << " (" << blaze::to_string(app.status) << ")\n";
            completion.set_value(1);
            return;
          }

          std::cout << "Application name: " << app.name << '\n';
          std::cout << "Application version: " << app.version << '\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
) {
  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()) {
    std::cout << "Initialize returned status "
              << static_cast<unsigned int>(app.status)
              << " (" << blaze::to_string(app.status) << ")\n";
    co_return blaze::make_error_code(app.status);
  }

  std::cout << "Application name: " << app.name << '\n';
  std::cout << "Application version: " << app.version << '\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");

  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]() -> blaze::coro::task<void> {
    const std::error_code ec = co_await run_example(session, websocket_api_key, client_id);
    completion.set_value(ec);
    co_return;
  }());

  const std::error_code ec = result.get();
  if (ec) {
    print_error_code("Initialize 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

Initialize statuses

ValueStatusReturned when
1okInitialization completed successfully.
2invalid_api_keywebsocket_api_key length is not exactly 21 characters.
4already_initializedThis session was already initialized earlier.
6internal_server_errorInitialization could not be completed because of a server-side internal error.
500client_id_too_shortclient_id is shorter than 4 characters. This is rejected locally before the request is sent.
501client_id_too_longclient_id is longer than 64 characters. This is rejected locally before the request is sent.
503client_id_blacklistedThe provided client_id is blacklisted for this application.
600app_not_foundNo application exists for the provided websocket_api_key.
601app_pausedThe target application exists but is currently paused.
602app_sessions_quota_exceededThe application has reached its allowed number of authorized sessions.

Connection-level shutdowns

Some initialization failures are reported as websocket shutdowns rather than as application.status.

Close codeMeaningWhen it can happen
4201rate_limitedThe session/IP is rate-limited before initialization can complete.
4202initalization_timed_outNo successful initialize happened within the required 15 seconds.
4204client_id_blacklistedThe server can close the session after returning client_id_blacklisted.
4205initialization_failedRepeated server-side failures prevented the session from being initialized.

Related page

Common pitfalls

Common C++ API misuse patterns, why they fail, and how to fix them.

create_account

Creates a new application account for the current initialized session.

On this page

Function variantsParametersResultChecking returned fieldsBehavior notesExampleInitialize statusesConnection-level shutdownsRelated page