Authentication

Logging in and out of the REST API

There is process flow for authenticating to Opsview within the Introduction in the Authentication section

Logging in

URL: /rest/login

  • GET - unimplemented
  • POST - get session token. Pass in username and password
  • PUT - unimplemented
  • DELETE - if session token is valid, deletes from session list, effectively a logout

📘

The opsview_rest command will automatically take care of authentication for you without having to post credentials to the login endpoint.

If a token cannot be generated, a 503 HTTP status code will be returned, with the text, “Error creating session token after 5 attempts”.

Example curl request:

$ curl -H 'Content-Type: application/json' -X 'application/json' -X POST -d '{"username":"admin","password":"initial"}' http://localhost/rest/login

Example response:

{
    "token": "7cd5652f7bfde4220211d063c166b263160a7d52"
}

The length of the token is 32 characters.

If you can pass the parameter, include_user_data=1, a user_data field will be returned in the response. This will contain the data from the /rest/user call.

Logging in to the API via AuthTkt

URL: /rest/login_tkt

  • POST - get session token. Pass in username
  • GET,PUT,DELETE - unimplemented

Required parameter:

  • username

This acts like /rest/login, but authenticates a user based on their auth_tkt cookie. This allows a web browser which has already been authenticated to connect to the REST API. The username is still required to be passed in as a secondary check so that knowing the cookie is not sufficient to gain access to the API.

Logging out

URL: /rest/logout

  • POST - deletes the session
  • GET,PUT,DELETE - unimplemented

Example opsview_rest request

opsview_rest --username=admin --password=initial --data-format=json --pretty POST logout

Expected response:

{
   "logout_via" : "REST API"
}

User information

URL: /rest/user

  • GET - returns user information for the currently authenticated user
  • POST,PUT,DELETE - unimplemented

This returns information about the user.

See include_user_data=1 in the login section above for fetching this information via a curl request when authenticating.

Example opsview_rest request:

$ /opt/opsview/coreutils/bin/opsview_rest --username=admin --password=initial --pretty GET user

Example response:

{
    "access_list": {
        "ACTIONALL": 1,
        "ADMINACCESS": 1,
        "VIEWALL": 1,
        ...
    },
    "fullname": "Admin user",
    "language": "",
    "name": "admin",
    "realm": "local",
    "role": "Administrator"
}