.. _Authenticate: 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 :doc:`../AccessControl` 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 :doc:`../Responses` for other errors and retry guidance. Examples -------- Authenticate with a password: .. TESTED_EXAMPLE: Authenticate_1 .. code-block:: json [{ "Authenticate": { "username": "john", "password": "love4Aperture!" } }] Response: .. TESTED_EXAMPLE: Authenticate_1_response .. code-block:: json [{ "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: .. TESTED_EXAMPLE: Authenticate_2 .. code-block:: json [{ "Authenticate": { "token": "adbp_jZ1QTOfDs0RrvzMzd5vSsLEcRintc14zlN9" } }] Response: .. TESTED_EXAMPLE: Authenticate_2_response .. code-block:: json [{ "Authenticate": { "status": 0, "session_token": "adbs_Z2nOUCAE37tlfcPUdeNGE5wtMRZvFYUn6iv", "session_token_expires_in": 36000, "refresh_token": "adbr_TxchBKOyerwLEbNnnhuoxtzSuC8ag0u9j5O", "refresh_token_expires_in": 360000 } }]