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.
| Field | Practical check |
|---|---|
application.name | application.name.empty() |
application.version | application.version.empty() |
Behavior notes
- Call
initializeonly after a successfulconnect. - The library sends the protocol version automatically. You provide only
websocket_api_keyandclient_id. client_idlength is validated locally before the request is sent.- If
status != blaze::status::ok,nameandversionare 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
| Value | Status | Returned when |
|---|---|---|
1 | ok | Initialization completed successfully. |
2 | invalid_api_key | websocket_api_key length is not exactly 21 characters. |
4 | already_initialized | This session was already initialized earlier. |
6 | internal_server_error | Initialization could not be completed because of a server-side internal error. |
500 | client_id_too_short | client_id is shorter than 4 characters. This is rejected locally before the request is sent. |
501 | client_id_too_long | client_id is longer than 64 characters. This is rejected locally before the request is sent. |
503 | client_id_blacklisted | The provided client_id is blacklisted for this application. |
600 | app_not_found | No application exists for the provided websocket_api_key. |
601 | app_paused | The target application exists but is currently paused. |
602 | app_sessions_quota_exceeded | The 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 code | Meaning | When it can happen |
|---|---|---|
4201 | rate_limited | The session/IP is rate-limited before initialization can complete. |
4202 | initalization_timed_out | No successful initialize happened within the required 15 seconds. |
4204 | client_id_blacklisted | The server can close the session after returning client_id_blacklisted. |
4205 | initialization_failed | Repeated server-side failures prevented the session from being initialized. |