Authentication

Log in, obtain an authorization token and log out

Most API endpoints expect the authorization token in the authorization HTTP header, exactly as returned by the login endpoint (no Bearer prefix). A token is valid for 24 hours or until logout. A request without a token is rejected with 401 and the plain-text body Missing token; a request with a malformed or expired token gets 401 and Invalid token. A request whose role is below the endpoint’s minimum user role gets 401 as well (see Responses).

Endpoints that do not require a token: login, GET /api/gui_info, GET /api/state, the health checks, GET /api/storage/captures/download and the syslog download endpoints. Their pages say so.

Which authentication sources are tried, and in which order, is defined by the AAA Configuration.

API

• Data:

  • USER_CREDENTIALS object:

    {
        "username": "admin",
        "password": "<password>"
    }

  • USER_TOKEN object:

    {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHBpcnkiOiI5NTAxNyIsImxvZ2luX2luc3RhbmNlIjoiMTE2NjYzNDY0OTMwNjI5MDcyNjIiLCJzb3VyY2UiOiJsb2NhbCIsInVzZXJuYW1lIjoiYWRtaW4ifQ.dDvguTl2XuLvrZuEvEFuHohZl55DoBpDYo-4d1r3qPE",
        "auth_source": "local",
        "user":
        {
            "id": 1,
            "username": "admin",
            "name": "default_administrator",
            "email": "support@profitap.com",
            "role": "admin",
            "active": true,
            "creation_time": 1783547340,
            "modification_time": 0,
            "last_access": 1790332362,
            "custom_config": {}
        },
        "role": "admin"
    }

    • token - authorization token to be sent in the authorization header of subsequent requests
    • auth_source - source that authenticated the user: local, radius, tacacs or ldap
    • user - the local user record; null unless auth_source is local
    • role - effective role of the session: viewer, operator or admin; always set
    • custom_config - reserved for GUI settings, currently always an empty object
• Login

  • Path: /api/login

  • Method: POST

  • Minimum user role: none (no token required)

  • Request body: USER_CREDENTIALS; both fields are mandatory

  • Response on success (200 OK):

    {
        "message": "Successfully logged in",
        "data": USER_TOKEN
    }

  • Response on wrong credentials (401 Unauthorized): {"message": "Failed to log in", "data": null}. The response is delayed by a few seconds to slow down password guessing.

  • Response on malformed JSON (400 Bad Request): {"message": "Could not parse payload: ...", "data": null}

  • Response on a missing field (500 Internal Server Error): {"message": "The password field is missing.", "data": null}

  • Notes: the default credentials are username admin, password admin. Change the password after the first login.

• Logout
  • Path: /api/logout
  • Method: POST
  • Minimum user role: viewer
  • Response on success (200 OK): {"message": "Successfully logged out", "data": null}
  • Response on failure (401 Unauthorized): Missing token or Invalid token (plain text), or {"message": "Failed to log out", "data": null} when the local user no longer exists
  • Notes: for a local session the token is invalidated on the device; using it again returns 401 with {"message": "Failed to log in", "data": null}. For radius, tacacs and ldap sessions the call succeeds but the token stays valid until it expires; discard it on the client side.

Back to Index