Hey! These docs are for version 6.5, which is no longer officially supported. Click here for the latest version, 6.7!

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"
}