Page tree
Skip to end of metadata
Go to start of metadata

Please read the General Integration Guide to learn the general concepts and common data structures used throughout the Argus API.


About User API

The Argus user APIs holds all the users of the system, and controls what they should be allowed to access in the system.

The main concept the is the user, which identifies on person with access to Argus. To make it easier to manage permissions you can have groups of members. If a permission is granted to a group, then all members of that group inherits that permission from the group. Users and groups are referred to collectively as subjects.

The system contains many roles, which are used to limit access to certain parts of the system. They are arranged in a hierarchy where different roles allow access to performing different functions. If a subject has a certain role, then that user also has access to all the roles and functions inherited by that role.

Roles are granted to subjects by granting them a permission to access the role. A permission grants a certain subject access to perform a certain role, for a certain customer. NOTE: Permissions check inheritance, so all members of the subject, have access to all the functions belonging to the role, for all sub-customers of the customer.

Detailed API documentation

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

Integration guide

User administration

Fetching a user

Fetching a user can be done either by ID or short name(i.e. username):

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user/1

If successful, this query will return a user model:

{
  "data": {
    "id": 1,
    "shortName": "dennis",
    "name": "Dennis R Stevenson",
	"customer": {"id": 1, "shortName": "Mnemonic"}
    ...
}

All endpoints for fetching, adding, searching/listing, updating and deleting a user return the same user datamodel.

See Swagger API documentation for details on the returned data model.


Adding a user

To create a user you need to provide customer(shortName or ID), a shortName and a name:

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user -d '{ 
	"customer": "Mnemonic", 
	"shortName": "dennis", 
	"name": "Dennis R Stevenson"
}'

The newly created user is returned

Updating a user

Updating the fields of the user is done using a PUT request to the user resource.

To update a user you need the short name or ID, and to provide at least one field to update:

curl -X PUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user -d '{ 
	"email": "dennis@example.com"
}'

The updated user is returned

Disabling a user

To disable a user you need the short name or ID of the user

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/useradmin/v2/user/dennis

The disabled user is returned

Reenabling a user

To reenable a user you need the short name or ID of the user

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/useradmin/v2/user/dennis/reenable

The reenabled user is returned

Unblocking a user

If a used has too many failed logon attempts, the user is blocked. 

Unblocking a user will allow that user to attempt to log in again. If the user has forgotten their password, it is possible to reset it

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/useradmin/v2/user/dennis/unblock

The unblocked user is returned

Reset user password

If a user has forgotten their password it is possible to reset it.

The reset password endpoint will reset the users password and email the new password to them.

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/useradmin/v2/user/dennis/resetpassword

List user permissions

To see the permissions that have been granted to a user you need the name or ID of the user

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user/dennis/permissions

This returns a list of all the permissions that have been granted to the user

Searching for users

Searching for users can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General Integration Guide to learn about general concepts for search endpoints.

Simple search

For simple search, the valid filtering parameters can be added as query parameters, which will ANDed together for each parameter.
If any parameter name is repeated, all the values for that parameter name will be combined according to the Swagger API documentation.

Providing no parameters will return all users

# search for users belonging to mnemonic matching the keyword "Stevenson" 
curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user?customer=Mnemonic&keyword=stevenson

The result will be a list of all users the current user has access to matching the query

Advanced search

Advanced searches allow combining multiple queries to get more fine grained searches.

Detailed information on how to build advanced searches using sub-criteria are found in the General integration guide.

All parameters available for user search are detailed in the Swagger API documentation.

# search for users that are either deleted or blocked
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user/search -d '{
	"includeDeleted": true,
	"subCriteria": [{
			"includeFlags": ["deleted"]
		}, {
			"includeFlags": ["blocked"]
		}]
	}
}'


Administrating user preferences

The user preferences store information about how the user has setup Argus(e.g. time zone and dashboard setting) as simple key/value pairs of text. It also contains some metadata about the user.

Listing out user preferences

It is possible to list out all the preferences of a user using the ID or short name of the user

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user/dennis/preferences

This will return a list of user preference models

{
  
  "data": {
    "key": "time.zone",
    "value": "Europe/Oslo",
      ...
}

All endpoints for fetching, adding, listing, and deleting user preferences return the same user preference datamodel.

See Swagger API documentation for details on the returned data model.


Adding or updating user preferences

To add or update user preferences, use the PUT method to send a map with the new preferences

curl -X PUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user/dennis/preferences -d '{ 
	"integration-guide.started": "true"
}'

This returns a list of the created or updated user preferences

Deleting user preferences

To delete a user preference you send a DELETE request to the preferences endpoint

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/useradmin/v2/user/dennis/preferences?key=time.zone&key=time.format.time

This returns a list of the deleted user preferences

Group administration

Fetching a group

Fetching a group can be done either by ID or short name(i.e. username):

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/group/2

If successful, this query will return a group model:

{
  "data": {
    "id": 2,
	"shortName": "mnemonic-developers", 
	"name": "Mnemonic developer users"
	"customer": {"id": 1, "shortName": "Mnemonic"}
    ...
}

All endpoints for fetching, adding, searching/listing, updating and deleting a group return the same group datamodel.

See Swagger API documentation for details on the returned data model.

Adding a group

To create a group you need to provide customer(shortName or ID), a shortName and a name:

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/group -d '{ 
	"customer": "Mnemonic", 
	"shortName": "mnemonic-developers", 
	"name": "Mnemonic developer users"
}'

The newly created user is returned

Updating a group

Updating the fields of the group is done using a PUT request to the group resource.

To update a group you need the short name or ID, and to provide at least one field to update:

curl -X PUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/group -d '{ 
	"name": "Mnemonic developers"
}'

The updated group is returned

Disabling a group

To disable a group you need the short name or ID of the group

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/useradmin/v2/group/mnemonic-developers

The disabled group is returned

Reenabeling a group

To reenable a group you need the short name or ID of the group

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/useradmin/v2/group/mnemonic-developers/reenable

The reenabled group is returned

Listing group members

To list the members of a group you need the ID or short name of the group

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/group/mnemonic-developers/members

This will return a list of the members of the group, which can be either users or groups 

Adding members to a group

If you want to add members to a group you need to know the short name or ID of the group you are adding them to, as well as the short name or ID of the subjects( users or groups) that you want to add as members

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/group/mnemonic-developers/members -d '{ 
	"subject": ["dennis", 1234]
}'

The subjects added to the group are returned

Removing members from a group

If you want to remove members from a group you need to know the short name or ID of the group you are removing them from, as well as the short name or ID of the subjects( users or groups) that you want to remove as members

curl -X DELETE -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/group/mnemonic-developers/members?subject=dennis

The removed subjects are returned

List group permissions

To see the permissions that have been granted to a group you need the name or ID of the group

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/group/mnemonic-developers/permissions

This returns a list of all the permissions that have been granted

Searching for groups

Searching for groups can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General Integration Guide to learn about general concepts for search endpoints.

Simple search

For simple search, the valid filtering parameters can be added as query parameters, which will ANDed together for each parameter.
If any parameter name is repeated, all the values for that parameter name will be combined according to the Swagger API documentation.

Providing no parameters will return all groups

# search for groups belonging to mnemonic matching the keyword "developers" 
curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/group?customer=Mnemonic&keyword=developers

The result will be a list of all groups the current user has access to matching the query

Advanced search

Advanced searches allow combining multiple queries to get more fine grained searches.

Detailed information on how to build advanced searches using sub-criteria are found in the General integration guide.

All parameters available for group search are detailed in the Swagger API documentation.

# search for groups that match "developers" but not "rookie"
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/user/search -d '{
	"subCriteria": [{
			"keywords": ["developers"]
		}, {
			"excluded": true,
			"keywords": ["rookie"]
		}]
	}
}'

Permission administration

Searching for permissions

Searching for permissions can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General Integration Guide to learn about general concepts for search endpoints.

Simple search

For simple search, the valid filtering parameters can be added as query parameters, which will ANDed together for each parameter.
If any parameter name is repeated, all the values for that parameter name will be combined according to the Swagger API documentation.

Providing no parameters will return all permissions

# search for permissions granted on customer Mnemonic
curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/permission?customer=Mnemonic

This query will return a list of permission models:

{
  "data": [
    	{
     	 "id": 1,
     	 "function": {
       		 "id": 2,
        	 "name": "CUSTOMER-ROLES"
        },
        "subject": {
          "id": 3,
          "shortName": "Gnhst",
          "name": "Gnhst",
          "type": "group",
          ...
        },
        "customer": {
          "name": "Mnemonic",
        },
	    ...    
	}
	]
}

The endpoints searching, granting, and revoking permissions return the same permission datamodel.

See Swagger API documentation for details on the returned data model.

Advanced search

Advanced searches allow combining multiple queries to get more fine grained searches.

Detailed information on how to build advanced searches using sub-criteria are found in the General integration guide.

All parameters available for group search are detailed in the Swagger API documentation.

# search for permissions that are given for "developers" but not the "CUSTOMER-ROLES" permissions
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/permission/search -d '{
	"customer": "Mnemonic"
	"subCriteria": [{
			"excluded": true,
			"function": ["CUSTOMER-ROLES"]
		}]
	}
}'

Granting a permission

To grant a permission you need to provide customer(shortName or ID) to provide the permission for, the role you want to grant, and the short name or ID of the group or user you want to grant the permission to:

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/permission -d '{ 
	"customer": "Mnemonic", 
	"subject": "dennis", 
	"function": "CUSTOMER-ROLES"
}'

The newly created permission is returned

Revoking a permission

To revoke a permission you need to know the ID of the permission you want to revoke:

curl -X DELETE -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/permission/1

The revoked permission is returned

Functions

Fetching a function

To fetch a function you need to know the name or ID of the function

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/function/VIEW-INTEGRATIONGUIDE

This returns the function model:

{
  "data": {
    "id": 1,
    "name": "INTEGRATIONGUIDE-READERS",
    "description": "Allows access to read the integration guide",
    "minimumSecurityLevel": "external",
    "flags": [
      "role"
    ],
    ...
  }
}

The endpoints searching and listing functions return the same function datamodel.

See Swagger API documentation for details on the returned data model.

Listing a functions children

To list a functions children you need the name or ID of the parent function

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/function/VIEW-INTEGRATIONGUIDE/children

This returns a list of all the children of the function

Listing a functions parents

To list a functions parents you need the name or ID of the child function

curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/function/VIEW-INTEGRATIONGUIDE/parents

This returns a list of all the parents of the function

Searching for functions

Searching for functions can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General Integration Guide to learn about general concepts for search endpoints.

Simple search

For simple search, the valid filtering parameters can be added as query parameters, which will ANDed together for each parameter.
If any parameter name is repeated, all the values for that parameter name will be combined according to the Swagger API documentation.

Providing no parameters will return all functions

# List functions that have at least security level "standard" 
curl -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/function?minimumSecurityLevel=standard

The result will be a list of all functions the current user has access to matching the query

Advanced search

Advanced searches allow combining multiple queries to get more fine grained searches.

Detailed information on how to build advanced searches using sub-criteria are found in the General integration guide.

All parameters available for group search are detailed in the Swagger API documentation.

# search for functions that are of securitylevel "standard" 
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/useradmin/v2/function/search -d '{
	"minimumSecurityLevel": "standard"
	"subCriteria": [{
			"excluded": true,
			"minimumSecurityLevel": "administrative"
		}]
	}
}'

  • No labels