Authenticate

Start a session with a username and password, or an assigned personal token.

Send this as the only command when no valid session exists. No input or output blobs are used.

Parameters

Parameter	Type / required	Default and behavior
username	string / conditional	Required with password. With token alone, the account is resolved from the token.
password	string / conditional	Provide password or token. If both are present, password authentication takes precedence.
token	string / conditional	Assigned personal token (adbp_ prefix); required when password is absent. A session or refresh token is not a personal token.

Details

The password path requires both username and password. The token path accepts token alone, or username and token. Generate and assign a personal token with GenerateToken and UpdateUser before using it here. Supplying both password and token does not perform two-factor authentication.

Client libraries manage the session header automatically. Direct protocol clients must send the returned session token on subsequent requests.

Response and recovery

Success returns status: 0, session_token, refresh_token, session_token_expires_in, and refresh_token_expires_in. The two expiry fields are durations in seconds from the server configuration. Token values are secrets; the example values below are illustrative.

Failure or empty result	Cause and recovery
Missing password and token, or password without username	Supply one of the documented authentication forms.
Authentication failed! or token lookup error	Check the username/password or use a personal token assigned to the intended account.

See Responses for validation, authentication, and permission error envelopes. Command errors use a negative status and an info message.

Examples

Authenticate to the db with user and password:

[{
    "Authenticate": {
        "username": "john",
        "password": "love4Aperture!"
    }
}]

Tokens shown here are from a session, and yours will differ in value, but will have the same length and prefix.

[{
    "Authenticate": {
        "status": 0,
        "session_token": "adbs_Z2nOUCAE37tlfcPUdeNGE5wtMRZvFYUn6iv",
        "session_token_expires_in": 36000,
        "refresh_token": "adbr_TxchBKOyerwLEbNnnhuoxtzSuC8ag0u9j5O",
        "refresh_token_expires_in": 360000
    }
}]

Authenticate to the db with token only:

[{
    "Authenticate": {
        "token": "adbp_jZ1QTOfDs0RrvzMzd5vSsLEcRintc14zlN9"
    }
}]

These values also are from an actual session, and yours will have the same format.

[{
    "Authenticate": {
        "status": 0,
        "session_token": "adbs_Z2nOUCAE37tlfcPUdeNGE5wtMRZvFYUn6iv",
        "session_token_expires_in": 36000,
        "refresh_token": "adbr_TxchBKOyerwLEbNnnhuoxtzSuC8ag0u9j5O",
        "refresh_token_expires_in": 360000
    }
}]