Skip to main content

REST API

The SecurEnvoy Access Management REST API lets you manage create, read, update, and delete your users and associated groups and applications.
To get started, you must first create an API key of type 'REST API'. Once generated, this key can be used to authenticate and interact with the REST API through tools such as postman. To use the REST API, call the API endpoint following this format:

https://{mytenant}.{environment}.securenvoy.directory/api/user/restapi/endpoint

You can then make a call to the API endpoint for the action you want to perform.

Endpoints​

Some API endpoints have actions that contain optional parameters which must be added to the end of the API call as shown here:

https://{mytenant}.{environment}.securenvoy.directory/api/user/restapi/endpoint?{param}={value}

For these optional parameters you can add multiple to one query as shown here:

https://{mytenant}.{environment}.securenvoy.directory/api/user/restapi/endpoint?{param1}={value}&{param2}={value}

Some API endpoints have actions that require mandatory parameters, these can be used as shown here:

https://{mytenant}.{environment}.securenvoy.directory/api/user/restapi/endpoint/{mandatoryParameter}

Users Endpoints​

GET​

/users - Gets a list of all users in the tenant. Optional filters:

  • sort (string): Field to sort data by.
    • Default value: id
  • sortOrder (string): Sorting Order.
    • Default value: asc
    • Available values: asc, desc
  • pageSize (int): Number of items per page.
    • Default value: 50
  • page (int): The page to return.
    • Default value: 1
  • username (string): Username of user(s) to return.
  • email (string): Email address of user(s) to return.
  • firstName (string): First name of the user(s) to return.
  • lastName (string): Last name of the user(s) to return.

/users/{userId} - Find a user by their id. Required parameters:

  • userId (string): Id of the user to find.

/users/{userId}/groups - Returns a list of groups a user belongs to. Required parameters:

  • userId (string): Id of the user to return groups for.

/users/{userId}/applications - Returns a list of applications assigned to a user. Required parameters:

  • userId (string): Id of the user to return applications for.

/users/username/{username} - Find a user by their username. Required parameters:

  • username (string): Username of the user to find.

POST​

/users - Creates a new user.

Request body:

{  
  "username": "string",  
  "email": "string",  
  "firstName": "string",  
  "middleName": "string",  
  "lastName": "string",  
  "userType": "user",  
  "phone": "string",  
  "mobile": "string",  
  "fax": "string",  
  "streetAddress": "string",  
  "city": "string",  
  "postalCode": "string",  
  "poBox": "string",  
  "state": "string",  
  "employeeNumber": "string",  
  "department": "string",  
  "jobTitle": "string",  
  "employmentType": "string",  
  "country": "Afghanistan",  
  "isLocked": true,  
  "isEnabled": true,  
  "aliases": [  
    "string"  
  ],  
  "customAttributes": [  
    {  
      "id": "string",  
      "name": "string",  
      "value": "string"  
    }  
  ],  
  "autoGeneratePassword": true,  
  "password": "string",  
  "mustChangePasswordOnLogon": true,  
  "sendEmail": true  
}

/users/{userId}/assigngroups - Assigns group(s) to a user. Required parameters:

  • userId (string): Id of the user to assign groups to.

Request Body - List of group ids to assign to the user:

[
	"string"
]

/users/{userId}/removegroups - Remove group(s) from a user. Required parameters:

  • userId (string): Id of the user to remove groups.

Request Body - List of group ids to remove from the user:

[
	"string"  
]

/users/{userId}/assignapplications - Assigns application(s) to a user. Required parameters:

  • userId (string): Id of the user to assign applications to.

Request Body - List of application ids to assign to the user:

[
	"string"
]

/users/{userId}/removeapplications - Removes application(s) from a user. Required parameters:

  • userId (string): Id of the user to remove applications from.

Request Body - List of application ids to remove from the user:

[  
	"string"  
]

PUT​

/users/{userId} - Updates an existing user. Required parameters:

  • userId (string): Id of the user to update.

Request body:

{
  "username": "string",
  "email": "string",
  "firstName": "string",
  "middleName": "string",
  "lastName": "string",
  "userType": "user",
  "phone": "string",
  "mobile": "string",
  "fax": "string",
  "streetAddress": "string",
  "city": "string",
  "postalCode": "string",
  "poBox": "string",
  "state": "string",
  "employeeNumber": "string",
  "department": "string",
  "jobTitle": "string",
  "employmentType": "string",
  "country": "Afghanistan",
  "isLocked": true,
  "isEnabled": true,
  "aliases": [
    "string"
  ],
  "customAttributes": [
    {
      "id": "string",
      "name": "string",
      "value": "string"
    }
  ],
  "autoGeneratePassword": true,
  "password": "string",
  "mustChangePasswordOnLogon": true,
  "sendEmail": true
}

DELETE​

/users/{userId} - Delete a user by their user id. Required parameters:

  • userId (string): Id of the user to delete.

/users/username/{username} - Delete a user by username. Required parameters:

  • username (string): username of the user to delete.

Credentials Endpoints​

GET​

/credentials/{userId} - Show the first and second factor credentials for a user. Required parameters:

  • userId (string): Id of the user to get credentials for.

POST​

/credentials/{userId} - Set the first and second factor credentials for a user. Required parameters:

  • userId (string): Id of the user to set credentials for.

Request body:

{
  "id": "string",
  "firstFactor": {
    "type": "password",
    "data": {}
  },
  "secondFactor": {
    "type": "password",
    "data": {},
    "remove": false
  }
}

/credentials/setpassword/{userId} - Set a password for a user. If the user already has a password set, it will be overwritten. Required parameters:

  • userId (string): Id of the user to set password for.

Request body:

{
  "autoGeneratePassword": true,
  "password": "string",
  "mustChangePasswordOnLogon": true,
  "sendEmail": true
}

Groups Endpoints​

GET​

/groups - Gets a list of all groups. Optional filters:

  • sort (string): Field to sort data by.
    • Default value: id
  • sortOrder (string): Sorting Order.
    • Default value: asc
    • Available values: asc, desc
  • pageSize (int): Number of items per page.
    • Default value: 50
  • page (int): The page to return.
    • Default value: 1
  • name (string): Name of the group to return.
  • description (string): Description of the group to return.

/groups/{groupId} - Finds a group by its id. Required parameters:

  • groupId (string): Id of the group to find.

/groups/{groupId}/users - Gets a list of users in a group. Required parameters:

  • groupId (string): Id of the group to return users assigned to.

POST​

/groups - Creates a new group.

Request body:

{
  "name": "string",
  "description": "string",
  "enforceSecondFactor": true
}

/groups/{groupId}/assignusers - Assigns users to a group. Required parameters:

  • groupId (string): Id of the group to add users to.

Request body - List of user ids for users to be added to the group:

[
	"string"
]

/groups/{groupId}/removeusers - Removes users from a group. Required parameters:

  • groupId (string): Id of the group(s) to remove users from.

Request body - List of user ids for users to be removed from the group:

[
	"string"
]

PUT​

/groups/{groupId} - Update an existing group. Required parameters:

  • groupId (string): Id of the group to update.

Request body:

{
  "name": "string",
  "description": "string",
  "enforceSecondFactor": true
}

DELETE​

/groups/{groupId} - Deletes a group by id. Required parameters:

  • groupId (string): Id of the group to delete.

Applications Endpoints​

GET​

/applications - Get a list of configured applications. Optional filters:

  • sort (string): Field to sort data by.
    • Default value: id
  • sortOrder (string): Sorting Order.
    • Default value: asc
    • Available values: asc, desc
  • pageSize (int): Number of items per page.
    • Default value: 50
  • page (int): The page to return.
    • Default value: 1
  • name (string): The name of the application.
  • label (string): The label of the application.

/applications/{applicationId}/users - Gets a list of users assigned to an application. Required parameters:

  • applicationId (string): Id of the application to return users assigned to.

POST​

/applications/{applicationId}/assignusers - Assign users to an application. Required parameters:

  • applicationId (string): Id of the application to assign users to.

Request body - List of user ids for users to assign to the application:

[
	"string"
]

/applications/{applicationId}/removeusers - Remove users from an application. Required parameters:

  • applicationId (string): Id of the application to remove users from.

Request body - List of user ids for users to remove from the application:

[
	"string"
]