Authenticate

Start a session using a password or an assigned personal token.

No existing session is required. No input or output blobs are used.

Parameters

• username (string): required with password; optional with token.

• password (string): supply this or token. Password takes precedence if both are supplied.

• token (string): complete personal token assigned to a user; session and refresh tokens are not accepted here.

Behavior

Submit Authenticate alone. A request containing any other command is rejected. With token alone, ApertureDB finds the account assigned that token. With a username, the token must belong to that account.

A successful sign-in returns tokens for the new session. If the user is at the max_sessions_per_user limit, the oldest sessions and their refresh tokens are revoked to make room. Sessions with expired refresh tokens no longer count toward the limit. Other sessions remain valid. See Access Control for revocation and lifetime rules.

Response

Success returns status: 0, session_token, refresh_token, session_token_expires_in, and refresh_token_expires_in. Lifetimes are in seconds. Keep both token values secret. Rejected credentials return a negative status and an info message inside the Authenticate command result. See Responses for other errors and retry guidance.

Examples

Authenticate with a password:

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

Response:

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

Authenticate with a personal token already assigned to a user:

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

Response:

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