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.
| 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 |
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
authorizeonly after successfulconnectandinitialize. - Login and password length are validated locally before the request is sent.
- If
credentials.licenseis provided, its length is also validated locally before the request is sent. credentials.commentis not transmitted by this overload.- If
credentials.type == blaze::credentials_type::email_password, the server expectscredentials.loginto be a valid email address. app_user_not_foundis used both for an unknown account and for invalid credentials.- If the server omits
levels,comment,ip_address,time_left, orlicense_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
| 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. |