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

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

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.

On this page