Back to top

nevisIDM Core REST API (v1)

Introduction

The nevisIDM Core REST API enables to query and manipulate of the managed identity objects in nevisIDM through CRUD operations. CRUD stands for Creating, Reading, Updating and Deleting resources.

Relationships between two resources are defined by their external IDs. The only way to (re)define the relationship between two resources is through the nevisIDM REST API. That is, by object creation with POST calls, by assignment through PUT calls, and by unassignment through DELETE calls.

The nevisIDM REST API also provides access to the properties of the different objects. Properties are dynamic fields that contain additional, customer-specific information about a object.

Managed identity objects

The identity objects of nevisIDM looks like this:

  • Client

    • A nevisIDM instance may have one ore more clients.
    • A client has zero or more users.
    • A client has zero or more applications.
    • A client has zero or more enterprise roles.

  • User

    • A user is unique on a client level.
    • A user cannot be moved to another client.
    • A user has zero or more profiles.
    • A user has zero or more credentials.
    • A user has zero or more enterprise roles.

  • Application

    • An application can belong to zero or more clients.
    • An application has zero or more roles.

  • Role

    • A role is unique on a client level.
    • A role cannot be moved to another client or application.

  • Enterprise role

    • An enterprise role is unique on a client level.
    • An enterprise role cannot be moved to another client.
    • An enterprise role has zero or more roles.

  • Profile

    • A profile is unique on a client level.
    • A profile cannot be moved to another client.
    • A profile has zero or one unit.
    • In the object model, a profile is connected to a role through an authorization.
    • In the REST API, a profile is directly connected to zero or more roles.
    • In the REST API, a profile has zero or more authorizations.

  • Unit

    • A unit is unique on a client level.
    • A unit cannot be moved to another client.
    • A unit has zero or one parent unit.
    • If a unit has no parent unit, it is considered as a root unit.
    • There may be multiple root units.

Updating an object - optimistic locking

When using the PATCH request to modify an object, it is possible that the originator of the request accesses and updates stale data. This occurs when the same object is being updated by another originator at the same time. This may result in accidental overwriting of data.

To ensure data consistency, the version field of the objects can be used upon modifying data. It is set to default when an object is created, and it is incremented each time an object is modified.

When including the version number in the body of the PATCH request, nevisIDM will check whether the version of the object being modified is up to date. If it is, the modification will be stored, if it is not, an error message will be returned with 409 Conflict status code.

Example request body

When updating the application with the given external ID (PATCH).

  • Request (application/json)

    • Body

      {
      "extId": "1001",
      "version": 10,
      "name": "Confluence",
      "url": "www.newurl.com/confluence/"
    }

  • Response 200

If the application with extId 1001 has the version of value 10.

  • Response 409

If the application with extId 1001 has the version of value different than 10.

  • Body

    {
        "errors": [{
                    "code": "errors.optimisticLockingFailure",
                    "message": "Row was updated or deleted by another transaction (or unsaved-value mapping was incorrect) : [ch.adnovum.nevisidm.service.dto.Application#1001]"
                  }]
      }

Please note that if the version number is not included in the request body, the object will be modified regardless of its version. This may lead to inconsistent data.

Pagination of result lists

When performing a GET request to retrieve a list of results, the result set can be limited in order to improve performance. By default, the number of results returned is set to 1000. To access the next page of results, a continuation token is used. The limit and/or continuation token are expected in the URL as query parameters ().

Example of pagination

When sending a GET request to the following URL: https://your-host/nevisidm/api/core/v1/clients?limit=3

  • Response 200 (application/json)

    • Body

      {
      "items": [{
        "created": "2018-09-09T00:00:00Z",
        "lastModified": "2018-12-21T14:38:45Z",
        "version": 1,
        "extid": "1000",
        "name": "client1"
      },
      {
        "created": "2018-09-09T00:00:00Z",
        "lastModified": "2018-12-21T14:38:45Z",
        "version": 1,
        "extid": "1001",
        "name": "client2"
      },
      {
        "created": "2018-09-09T00:00:00Z",
        "lastModified": "2018-12-21T14:38:45Z",
        "version": 1,
        "extid": "1002",
        "name": "client3"
      }],
      "_pagination": {
        "continuationToken": "1536444000000_1002",
        "limit": 3
      }
    }

The continuationToken in the response body can be used to retrieve the next set of results by including it in the URL: https://your-host/nevisidm/api/core/v1/clients?limit=3&continuationToken=1536444000000_1002

Information classification with the REST API – GDPR business case

The content of this section can also be found at:

NevisIDM Reference Guide - section “Appendix A - Use Cases” - “Information classification with the REST API – GDPR business case”

The General Data Protection Regulation (GDPR) is a regulation issued by the European Union to strengthen and unify data protection. The REST API of nevisIDM allows marking user-related data in order to classify information, as is required in the GDPR business case.

Configuration

Marking user-related data is possible through client policy configuration. The following is a sample configuration of the client policy:

data.classifications=[gov, sensitive, personal]

data.classifications.personal.user=[name.firstName, name.familyName, contacts.mobile]
data.classifications.sensitive.user=[birthDate]
data.classifications.gov.user=[languageCode]

data.classifications.personal.user.properties=[propertyName1, propertyName2]

data.classifications.personal.profile=[remarks, modificationComment]
data.classifications.gov.profile=[profileState]

data.classifications.personal.profile.properties=[propertyName1, propertyName2]

The declaration of the customized classification levels occurs in the client policy configuration parameter _data.classifications{_}. The only limitation on the defined levels is that they have to match the following regular expression: [a-zA-Z0-9]+.

The declaration of fields occurs in line with the syntax data.classifications.<level>.<object>.

Before you are going to use a classification (level), do not forget to declare it in the client policy configuration parameter data.classificationsfirst. Otherwise a validation error will occur. For example, the following client policy configuration will not be accepted:

data.classifications=[gov, sensitive, personal]
data.classifications.undefined.user=[name.firstName,name.familyName, contacts.mobile]

The validation of fields enforces the rule set of the object. Therefore, the validation does not accept any item that is not part of the object returned by the corresponding REST service. The supported objects are those of the user and profile. Moreover, user properties and profile properties can be classified as well. The validation is case sensitive and the hierarchical relationships among fields are enforced, too. Hence, the following scenarios would be rejected:

data.classifications.personal.user=[firstName, contacts.MOBILE]
data.classifications.sensitive.user=[randomName]
data.classifications.gov.user=[mobile]

REST response format

The following responses are only returned in the format shown below if you have configured an applicable client policy.

When querying a single user:

//GET /users/12345
{
"extId": "12345",
"name": {
  "firstName": "Maria",
  "lastName": "Meier"
 },
 "_classifications": {
   "personal": ["name.firstName", "birthDate", "contacts.mobile"],
   "sensitive": ["birthDate"],
   "gov": ["language"]
 }
}

When querying a list of users:

//GET /clients/{extId}/users/
{
"items": [
 {
   "extId": "12345",
   "name": {
     "firstName": "Maria",
     "lastName": "Meier"
   }
 }
],
 "_classifications": {
   "personal": ["name.firstName", "name.familyName", "contacts.mobile"],
   "sensitive": ["birthDate"],
   "gov": ["languageCode"]
 }
}

When querying properties:

//GET /{clientExtId}/profiles/{extId}/properties/
{
"propertyName1": "value1",
"propertyName2": "value2",
"propertyNameN": "valueN",
 "_classifications": {
   "personal": ["propertyName1", "propertyName2"],
 }
}

Tags

since 2.73

New calls are annotated with the nevisIDM version from which they are available from.

Selfadmin

Calls that can be used for self-administration are marked with the SELFADMIN tag. Calls for self-administration sent by a user to view or modify his own data only require the permission AccessControl.SelfAdmin. However, if someone else other than the user wants to modify the data of this user, other permissions are required, such as AccessControl.UserView or AccessControl.UserDelete. For more details, see the chapters that describe the relevant services.

Deprecated

Calls that can no longer be used are marked with the DEPRECATED tag.

Common errors

HTTP response codes

The following common error codes are available:

  • 401 - The caller user is unauthorized (not logged in).

  • 403 - The caller user has no right to access the target data room or entity type.

  • 404 - There is no entity with the external ID set in the request URI (the requested entity could not be found).

  • 409 - The request could not be completed due to a conflict with the current state of the target resource. For example, the target resource may have been modified concurrently.

  • 422 - The request format is valid, but the values are violating business rules. For example, a mandatory value is missing, a read-only value has been changed, or a value represents an invalid state. This error code always refers to business errors.

  • 500 - A technical, non-business-related error has occurred on the server side.

HTTP response object

In case of error, a JSON object is returned with the following content:

  • errorCode - A unique and short identifier of the error (string).

  • message - A short textual description of the error (string).

Important notes

  • The nevisIDM REST API is an individual API. Its versioning is independent from other APIs.

  • You must be logged in to be able to use the nevisIDM REST API.

  • The data room concept is valid for this API (see the nevisIDM reference guide, chapter “Authorization in nevisIDM”). This means that you might receive different result sets and might be able to create or modify different resources than another caller, depending on the nevisIDM roles assigned to you.

  • All data that goes through the REST API is validated on the server side before processing. It is important, however, that you validate the data on the client side as well.

  • Note that the received data must not fully represent the object model of the nevisIDM web application. This is because not all fields of an object are exposed.

  • When you use PATCH to update resources with the API, all “null” values are ignored. Note that for some fields you cannot set the attributes back to “empty”.

Clients

Clients are representing “virtual organizations” or tentants. In some cases, our customers want to handle different organizations separately. Consider for example the customer McDanold’s, a fake fast food restaurant. This customer is present in different markets: EMEA, ASPAC and AMERICAS. The organizations in the different markets have to fulfil different legal obligations (for example, different policies for credentials), may have unique organizational structures, use different devices and software, and so on. Thus, it makes sense to handle each market separately. Another customer, a holding, owns companies in different industries with different profiles. Governmental customers may need separate clients for different departments (e.g., police, fire and immigration).

Clients can have zero to many users, applications, enterprise roles, units and policies. All resources, except for applications, cannot exist without a client. Thus, it is not possible to unassign the resources from the client, nor is it possible to reassign them to other clients.

The REST API only supports the reading of clients. The creation, modification and deletion of clients is not supported.

Note that the unassignment of an application from a client makes the application inaccessible for all users of the client.

Client

The client DTO has the following fields:

  • extId - External ID of the client. Can only be set on creation.

  • name - Internal name of the client (string).

  • displayName - Language-dependent name of the client (object).

    • EN - Client name in English (string).
    • DE - Client name in German (string).
    • FR - Client name in French (string).
    • IT - Client name in Italian (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

User

The user DTO has the following fields:

  • extId - The external ID of the user. Can only be set on creation.

  • clientExtId - The external ID of the client the user belongs to (string).

  • userState - The state of the user (string).

  • loginId - The login ID (username) of the user (string).

  • languageCode - The default language of the user (string).

  • isTechnicalUser - Determines whether the user is a regular user like a real person, or a technical user like another software (boolean).

  • name - The name of the user (object).

    • title - The title of the user (string).
    • firstName - The first name of the user (string).
    • familyName - The last name of the user (string).

  • sex - The biological sex of the user. This is not the same as legal gender (string).

  • gender - The gender of the user. Possible values are ‘female’, ‘male’ and ‘other’ (Note: The gender value ‘other’ is only supported if the policy ‘application.feature.othergender.enabled’ is enabled for the client of the user.) (string).

  • birthDate - The user’s date of birth in ISO format (string).

  • address - The address of the user (object).

    • countryCode - The ISO country code of the user (string).
    • city - The city where the user lives (string).
    • postalCode - The postal code (or ZIP code) of the user (string).
    • addressline1 - Free text for supplementary address information (string).
    • addressline2 - Free text for supplementary address information (string).
    • street - the street of the user (string).
    • houseNumber - The house number of the user (string).
    • dwellingNumber - The dwelling number (string). This number is relevant in combination with the user’s house number.
    • postOfficeBoxText - Describes the term “post box” according to the accepted form in the given country (string).
    • postOfficeBoxNumber - The number of the post box (number).

  • contacts - Telephone numbers and e-mail addresses on which the user can be contacted (object).

    • telephone - The number of the user’s landline (string).
    • telefax - The fax number of the user (string).
    • mobile - The cellphone number of the user (string).
    • email - the e-mail address of the user (string).

  • validity - The validity period of the user entity (object).

    • to - The end date of the user’s validity period in ISO format (string).
    • from - The start date of the user’s validity period in ISO format (string).

  • remarks - General textual remark about the user (string).

  • modificationComment - Textual comment on the last modification (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (string).

Application

The application DTO has the following fields:

  • extId - External ID of the application (read-only string).

  • name - Internal name of the application (string).

  • description - Textual description of the application (string).

  • url - URL of the application.

  • displayed - Determines whether the application must be displayed on nevisPortal (boolean).

  • displayName - Language-dependent name of the application (object).

    • EN - Application name in English (string).
    • DE - Application name in German (string).
    • FR - Application name in French (string).
    • IT - Application name in Italian (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Enterprise Role

The enterprise role DTO has the following fields:

  • extId - The external ID of the enterprise role (string).

  • clientExtId - The external ID of the client to which the enterprise role belongs (string).

  • name - The name of the enterprise role (string).

  • description - The textual description of the enterprise role (string).

  • displayName - The language-dependent name of the enterprise role (object).

    • EN - The enterprise role name in English (string).
    • DE - The enterprise role name in German (string).
    • FR - The enterprise role name in French (string).
    • IT - The enterprise role name in Italian (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (string).

  • lastModified - The date when the entity was last modified (string).

Clients

Get clients
GET/clients

Returns all clients in the system.

since 2.73

Required permissions

AccessControl.ClientView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "1001",
      "name": "McDanold's ASPAC",
      "displayName": {
        "EN": "McDanold's ASPAC",
        "DE": "McDanold's ASPAC",
        "FR": "McDanold's ASPAC",
        "IT": "McDanold's ASPAC"
      },
      "version": 2,
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    },
    {
      "extId": "1000",
      "name": "McDanold's EMEA",
      "displayName": {
        "EN": "McDanold's EMEA",
        "DE": "McDanold's EMEA",
        "FR": "McDanold's EMEA",
        "IT": "McDanold's EMEA"
      },
      "version": 0,
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1502928000_1000",
    "limit": 1000
  }
}

Client

Get client
GET/clients/{extId}

Returns the client with the given external ID.

since 2.71

Required permissions

AccessControl.ClientView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1000",
  "name": "McDanold's EMEA",
  "displayName": {
    "EN": "McDanold's EMEA",
    "DE": "McDanold's EMEA",
    "FR": "McDanold's EMEA",
    "IT": "McDanold's EMEA"
  },
  "version": 0,
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2017-08-17T00:00:00Z"
}

Client users

Get client users
GET/clients/{extId}/users

Returns all users of the client with the given external ID.

since 2.71

Required permissions

AccessControl.ClientView, AccessControl.UserView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/users
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "12314wsss",
      "clientExtId": "1000",
      "userState": "active",
      "version": 0,
      "loginId": "testUser",
      "languageCode": "en",
      "isTechnicalUser": false,
      "name": {
        "title": "Mr.",
        "firstName": "John",
        "familyName": "Doe"
      },
      "sex": "male",
      "birthDate": "1969-04-12",
      "address": {
        "countryCode": "ch",
        "city": "Zurich",
        "postalCode": "123414",
        "addressline1": "PostBox 1241",
        "addressline2": "Company XYZ",
        "street": "Poststreet",
        "houseNumber": "12",
        "dwellingNumber": "102B",
        "postOfficeBoxText": "PostBox",
        "postOfficeBoxNumber": 1241
      },
      "contacts": {
        "telephone": "+41781254153",
        "telefax": "+41781254154",
        "mobile": "+41781254156",
        "email": "john.doe@adnovum.ch"
      },
      "validity": {
        "from": "2016-12-31T12:00:00Z",
        "to": "2022-01-01T12:00:00Z"
      },
      "remarks": "This is test user john doe",
      "modificationComment": "Adjusted his address",
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    },
    {
      "extId": "12314abc",
      "clientExtId": "1000",
      "userState": "active",
      "version": 0,
      "loginId": "testUser2",
      "languageCode": "en",
      "isTechnicalUser": false,
      "name": {
        "title": "Mr.",
        "firstName": "Peter",
        "familyName": "Doe"
      },
      "sex": "male",
      "birthDate": "1969-04-12",
      "address": {
        "countryCode": "hu",
        "city": "Budapest",
        "postalCode": "123414",
        "addressline1": "PostBox 1241",
        "addressline2": "Company XYZ",
        "street": "Poststreet",
        "houseNumber": "12",
        "dwellingNumber": "102B",
        "postOfficeBoxText": "PostBox",
        "postOfficeBoxNumber": 1241
      },
      "contacts": {
        "telephone": "+36181254153",
        "telefax": "+36181254154",
        "mobile": "+36181254156",
        "email": "peter.doe@adnovum.ch"
      },
      "validity": {
        "from": "2016-12-31T12:00:00Z",
        "to": "2022-01-01T12:00:00Z"
      },
      "remarks": "This is test user peter doe",
      "modificationComment": "Adjusted his address",
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1502928000_12314abc",
    "limit": 100
  }
}

Client applications

Get client applications
GET/clients/{extId}/applications

Returns all applications of the client with the given external ID.

since 2.71

Required permissions

AccessControl.ClientView, AccessControl.ApplicationView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/applications
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "1001",
      "version": 10,
      "name": "Confluence",
      "description": "Confluence is used to store documents.",
      "url": "www.example.com/confluence/",
      "displayed": true,
      "displayName": {
        "EN": "Confluence",
        "DE": "Confluence",
        "FR": "Confluence",
        "IT": "Confluence"
      },
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    },
    {
      "extId": "1000",
      "version": 0,
      "name": "Jira",
      "description": "Jira is for ticketing.",
      "url": "www.example.com/Jira/",
      "displayed": true,
      "displayName": {
        "EN": "Jira",
        "DE": "Jira",
        "FR": "Jira",
        "IT": "Jira"
      },
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1502928000_1000",
    "limit": 100
  }
}

Client applications

Assign application
PUT/clients/{extId}/applications/{applicationExtId}/

Assigns the application with the given external ID to the client with the given external ID.

since 2.74

Required permissions

AccessControl.ClientApplAssign

Example URI

PUT https://your-host/nevisidm/api/core/v1/clients/1000/applications/1000/
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

applicationExtId
string (required) Example: 1000

ExtID of the application to be assigned.

Response  204

Unassign application
DELETE/clients/{extId}/applications/{applicationExtId}/

Unassigns the application with the given external ID from the client with the given external ID.

since 2.74

Required permissions

AccessControl.ClientApplDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/clients/1000/applications/1000/
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

applicationExtId
string (required) Example: 1000

ExtID of the application to be assigned.

Response  204

Client enterprise roles

Get client eroles
GET/clients/{extId}/eroles

Returns all enterprise roles of the client with the given external ID.

since 2.75.2

Required permissions

AccessControl.ClientView, AccessControl.EnterpriseRoleView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/eroles
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "234",
      "clientExtId": "1000",
      "version": 0,
      "name": "erole1",
      "description": "erole1",
      "displayName": {
        "EN": "erole1",
        "DE": "erole1",
        "FR": "erole1",
        "IT": "erole1"
      },
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    },
    {
      "extId": "231",
      "clientExtId": "1000",
      "version": 0,
      "name": "erole2",
      "description": "erole2",
      "displayName": {
        "EN": "erole2",
        "DE": "erole2",
        "FR": "erole2",
        "IT": "erole2"
      },
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1502928000_231",
    "limit": 100
  }
}

Client units

Get client units
GET/clients/{extId}/units

Returns all units of the client with the given external ID.

since 2.73

Required permissions

AccessControl.ClientView, AccessControl.UnitView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/units
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "102",
      "parentUnitExtId": "2311",
      "clientExtId": "1000",
      "version": 0,
      "hierarchicalName": "2311/102",
      "name": "MyUnit1",
      "location": "something",
      "description": "something",
      "displayName": {
        "EN": "MyUnit1",
        "DE": "MyUnit1",
        "FR": "MyUnit1",
        "IT": "MyUnit1"
      },
      "abbreviation": {
        "EN": "MU1",
        "DE": "MU1",
        "FR": "MU1",
        "IT": "MU1"
      },
      "profileless": true,
      "modificationComment": "blabla",
      "validity": {
        "from": "2017-08-17T00:00:00Z",
        "to": "2027-08-17T00:00:00Z"
      },
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    },
    {
      "extId": "100",
      "parentUnitExtId": "2311",
      "clientExtId": "1000",
      "version": 0,
      "hierarchicalName": "2311/100",
      "name": "MyUnit2",
      "location": "something",
      "description": "something",
      "displayName": {
        "EN": "MyUnit2",
        "DE": "MyUnit2",
        "FR": "MyUnit2",
        "IT": "MyUnit2"
      },
      "abbreviation": {
        "EN": "MU2",
        "DE": "MU2",
        "FR": "MU2",
        "IT": "MU2"
      },
      "profileless": true,
      "modificationComment": "blabla",
      "validity": {
        "from": "2017-08-17T00:00:00Z",
        "to": "2027-08-17T00:00:00Z"
      },
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1502928000_100",
    "limit": 100
  }
}

Client policies experimental

Get client policies
GET/clients/{extId}/policies/

Returns all policies of the client with the given external ID.

Required permissions

AccessControl.ClientView, AccessControl.PolicyConfigurationView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/policies/
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "items":[
  {
   "extId": "99990100",
   "clientExtId": "1000",
   "description": "sendingMethod=PDFemail", //can be also freetext
   "name": "TicketPolicyForPDFEmailSending",
   "policyType": "TicketPolicy",
   "defaultPolicy": true,
   "version": 0,
   "created": "2018-04-24T14:22:19Z",
   "lastModified": "2018-04-24T14:22:19Z"
  },
  {
   "extId": "99990049",
   "clientExtId": "1000",
   "description": "sendingMethod=SMS", //can be also freetext
   "name": "TicketPolicyForSMSSending",
   "policyType": "TicketPolicy",
   "defaultPolicy": true,
   "version": 43,
   "created": "2018-04-24T14:22:19Z",
   "lastModified": "2018-04-24T14:22:19Z"
  }
 ],
  "_pagination": {
     "continuationToken": "1524579739_99990049",
     "limit":100
  }
}

Client personal questions experimental

Get personal questions
GET/clients/{extId}/personal-questions

Returns all personal questions of the client with the given external ID.

Required permissions

AccessControl.ClientView, AccessControl.PersonalQuestionView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/personal-questions
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extid": "102",
      "clientExtId": "1000",
      "version": 0,
      "description": "something",
      "stateName": "active",
      "displayName": {
        "EN": "Question1",
        "DE": "Question1",
        "FR": "Question1",
        "IT": "Question1"
      },
      "content": {
        "EN": "QuestionContent1",
        "DE": "QuestionContent1",
        "FR": "QuestionContent1",
        "IT": "QuestionContent1"
      }
    },
    {
      "extid": "101",
      "clientExtId": "1000",
      "version": 0,
      "description": "something",
      "stateName": "active",
      "displayName": {
        "EN": "Question2",
        "DE": "Question2",
        "FR": "Question2",
        "IT": "Question2"
      },
      "content": {
        "EN": "QuestionContent2",
        "DE": "QuestionContent2",
        "FR": "QuestionContent2",
        "IT": "QuestionContent2"
      }
    }
  ],
  "_pagination": {
    "continuationToken": "1524579739_101",
    "limit": 100
  }
}

Create new personal question
POST/clients/{extId}/personal-questions

Creates a new personal question for the client with the given external ID.

Required permissions

AccessControl.ClientView, AccessControl.PersonalQuestionCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/clients/1000/personal-questions
URI Parameters
HideShow
extId
string (required) Example: 1000

ExtID of the client.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1003",
  "clientExtId": "1000",
  "version": 1,
  "description": "something",
  "stateName": "active",
  "displayName": {
    "DE": "QuestionNew",
    "EN": "QuestionNew",
    "FR": "QuestionNew",
    "IT": "QuestionNew"
  },
  "content": {
    "DE": "QuestionNewContent",
    "EN": "QuestionNewContent",
    "FR": "QuestionNewContent",
    "IT": "QuestionNewContent"
  }
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/personal-questions/1003

Applications

These endpoints enable the caller

  • to create and delete applications,

  • to obtain a given application resource, and

  • to list or change the roles assigned to the given application.

An application can belong to many clients. It may have zero to many roles. As roles are application-specific, a role can only be assigned to one application.

Please note that if you delete an application, it is no longer accessible for all users of all clients.

Application

The application DTO has the following fields:

  • extId - External ID of the application (read-only string).

  • name - Internal name of the application (string).

  • description - Textual description of the application (string).

  • url - URL of the application.

  • displayed - Determines whether the application must be displayed on nevisPortal (boolean).

  • displayName - Language-dependent name of the application (object).

    • EN - Application name in English (string).
    • DE - Application name in German (string).
    • FR - Application name in French (string).
    • IT - Application name in Italian (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Role

The role DTO has the following fields:

  • extId - The external ID of the role (read-only string).

  • applicationExtId - The external ID of the application the role belongs to (string).

  • applicationName - The name of the application the role belongs to (string).

  • name - The name of the role (string).

  • description - The textual description of the role (string).

  • version - The version used for optimistic locking (number).

  • created - The creation date of the entity (read-only string).

  • lastModified - The date when the entity was last modified (string).

Applications

Create application
POST/applications/

Creates a new application.

since 2.74

Required permissions

AccessControl.ApplicationCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/applications/
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1001",
  "version": 10,
  "name": "Confluence",
  "description": "Confluence is used to store documents.",
  "url": "www.example.com/confluence/",
  "displayed": true,
  "displayName": {
    "EN": "Confluence",
    "DE": "Confluence",
    "FR": "Confluence",
    "IT": "Confluence"
  }
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/applications/1001

Applications

Get application
GET/applications/{extId}

Returns the application with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.ApplicationView

Example URI

GET https://your-host/nevisidm/api/core/v1/applications/1001
URI Parameters
HideShow
extId
string (required) Example: 1001

ExtID of the application.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1001",
  "version": 10,
  "name": "Confluence",
  "description": "Confluence is used to store documents.",
  "url": "www.example.com/confluence/",
  "displayed": true,
  "displayName": {
    "EN": "Confluence",
    "DE": "Confluence",
    "FR": "Confluence",
    "IT": "Confluence"
  },
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2017-08-17T00:00:00Z"
}

Update application
PATCH/applications/{extId}

Updates the application with the given external ID.

since 2.74

Required permissions

AccessControl.ApplicationView, AccessControl.ApplicationModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/applications/1001
URI Parameters
HideShow
extId
string (required) Example: 1001

ExtID of the application.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "version": 10,
  "name": "Confluence",
  "description": "Confluence is used to store documents.",
  "url": "www.example.com/confluence/",
  "displayed": true,
  "displayName": {
    "EN": "Confluence",
    "DE": "Confli",
    "FR": "Confluence",
    "IT": "Confluence"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "extId": "1001",
 "version": 11,
 "name": "Confluence",
 "description": "Confluence is used to store documents.",
 "url": "www.example.com/confluence/",
 "displayed": true,
 "displayName": {
  "EN":"Confluence",
  "DE":"Confli",
  "FR":"Confluence",
  "IT":"Confluence"
 }
 "created": "2017-08-17T00:00:00Z",
 "lastModified": "2017-08-17T00:00:00Z"
}

Delete application
DELETE/applications/{extId}

since 2.74

Deletes the application with the given external ID.

Required permissions

AccessControl.ApplicationDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/applications/1001
URI Parameters
HideShow
extId
string (required) Example: 1001

ExtID of the application.

Response  204

Application roles

Get application roles
GET/applications/{extId}/roles

Returns all roles of the application with the given external ID.

Required permissions

AccessControl.ApplicationView, AccessControl.RoleView

Example URI

GET https://your-host/nevisidm/api/core/v1/applications/1001/roles
URI Parameters
HideShow
extId
string (required) Example: 1001

ExtID of the application.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "233",
      "applicationExtId": "1001",
      "applicationName": "Confluence",
      "version": 0,
      "name": "regularRole",
      "description": "role of normal users",
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    },
    {
      "extId": "211",
      "applicationExtId": "1001",
      "applicationName": "Confluence",
      "version": 0,
      "name": "adminRole",
      "description": "role of admins",
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1502928000_211",
    "limit": 100
  }
}

Create role
POST/applications/{extId}/roles

Creates a new role for the application with the given external ID.

since 2.74

Required permissions

AccessControl.RoleCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/applications/1001/roles
URI Parameters
HideShow
extId
string (required) Example: 1001

ExtID of the application.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1020",
  "name": "readonlyRole",
  "description": "role of read-only users"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/roles/1020

Application properties

Get properties
GET/applications/{extId}/properties/

Returns all properties of the application with the given external ID, as an object of key-value pairs. If there are no properties found, an empty object is returned. Properties are additional, customer-specific attributes of an entity.

since 2.74

Required permissions

AccessControl.ApplicationView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/applications/1001/properties/
URI Parameters
HideShow
extId
string (required) Example: 1001

ExtID of the application.

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "propertyKey1" : "propertyValue1",
 "propertyKey2" : "propertyValue2",
}

Update application
PATCH/applications/{extId}/properties/

Updates the properties of the application with the given external ID. The request body must contain an object of key-value property pairs.

since 2.74

Required permissions

AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView, AccessControl.PropertyValueCreate, AccessControl.PropertyValueModify, AccessControl.PropertyValueDelete

Example URI

PATCH https://your-host/nevisidm/api/core/v1/applications/1001/properties/
URI Parameters
HideShow
extId
string (required) Example: 1001

ExtID of the application.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "propertyKey1" : "propertyNewValue1",
 "propertyKey2" : "propertyValue2",
 "propertyKey3" : "propertyNewValue3",
}

User REST Service

Users build the core element of the system.

A user can have zero to many credentials of different types. During its entire lifetime, a credential belongs to only one particular user. The nevisIDM reference guide describes how many credentials of a certain type a user can possess.

A user can have zero to many profiles. Profiles connect a user to roles and units.

Profiles and credentials strictly belong to one particular user. It is not possible to reassign a profile or a credential to another user.

User external IDs are unique per client only, not globally. Therefore, you must always set the target client.

User DTO

The user DTO has the following fields:

  • extId - The external ID of the user. Can only be set on creation.

  • clientExtId - The external ID of the client the user belongs to (string).

  • userState - The state of the user (string).

  • loginId - The login ID (username) of the user (string).

  • languageCode - The default language of the user (string).

  • isTechnicalUser - Determines whether the user is a regular user like a real person, or a technical user like another software (boolean).

  • name - The name of the user (object).

    • title - The title of the user (string).
    • firstName - The first name of the user (string).
    • familyName - The last name of the user (string).

  • sex - The biological sex of the user. This is not the same as legal gender (string).

  • gender - The gender of the user. Possible values are ‘female’, ‘male’ and ‘other’ (Note: The gender value ‘other’ is only supported if the policy ‘application.feature.othergender.enabled’ is enabled for the client of the user.) (string).

  • birthDate - The user’s date of birth in ISO format (string).

  • address - The address of the user (object).

    • countryCode - The ISO country code of the user (string).
    • city - The city where the user lives (string).
    • postalCode - The postal code (or ZIP code) of the user (string).
    • addressline1 - Free text for supplementary address information (string).
    • addressline2 - Free text for supplementary address information (string).
    • street - the street of the user (string).
    • houseNumber - The house number of the user (string).
    • dwellingNumber - The dwelling number (string). This number is relevant in combination with the user’s house number.
    • postOfficeBoxText - Describes the term “post box” according to the accepted form in the given country (string).
    • postOfficeBoxNumber - The number of the post box (number).

  • contacts - Telephone numbers and e-mail addresses on which the user can be contacted (object).

    • telephone - The number of the user’s landline (string).
    • telefax - The fax number of the user (string).
    • mobile - The cellphone number of the user (string).
    • email - the e-mail address of the user (string).

  • validity - The validity period of the user entity (object).

    • to - The end date of the user’s validity period in ISO format (string).
    • from - The start date of the user’s validity period in ISO format (string).

  • remarks - General textual remark about the user (string).

  • modificationComment - Textual comment on the last modification (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (string).

Profile DTO

The profile DTO has the following fields:

  • extId - The external ID of the profile (read-only string).

  • userExtId - The external ID of the user to whom the profile belongs (read-only string).

  • unitExtId - The external ID of the unit to which the profile belongs (read-only string).

  • clientExtId - The external ID of the client to which the policy belongs (read-only string).

  • deputedProfileExtId - The external ID of the deputed profile (read-only string).

  • name - The name of the profile (string).

  • profileState - The state of the profile (string).

  • isDefaultProfile - Determines whether the profile is default or not (boolean).

  • remarks - Textual remark regarding the profile (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the profile (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

The consent create DTO has the following fields:

  • termsExtId - External ID of the terms.

Terms DTO

The terms get DTO has the following fields:

  • extId - The external id of the Terms object (string).

  • name - The name of the Terms object (string).

  • active - Determines whether the terms are active or not (boolean).

  • silentAcceptance - Determines whether the terms are accepted silently or not (boolean).

  • termsVersion - The version of the Terms (string).

  • created - The creation date (Date).

  • lastModified - The date of the last modification (Date).

  • urls - Actual Terms and Conditions pages (string: string pairs).

  • applicationExtIds - List of external ids of the applications for which the terms are assigned.

Users

Create user
POST/{clientExtId}/users/

Creates a new user for the client with the given external ID.

since 2.71

Required permissions

AccessControl.UserCreate, AccessControl.PolicyConfigurationView, AccessControl.UserCreateTechUser (for creating technical users only)

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "4254",
  "userState": "active",
  "loginId": "testUser",
  "languageCode": "en",
  "isTechnicalUser": false,
  "name": {
    "title": "Mr.",
    "firstName": "John",
    "familyName": "Doe"
  },
  "sex": "male",
  "gender": "male",
  "birthDate": "1969-04-12",
  "address": {
    "countryCode": "ch",
    "city": "Zurich",
    "postalCode": "123414",
    "addressline1": "PostBox 1241",
    "addressline2": "Company XYZ",
    "street": "Poststreet",
    "houseNumber": "12",
    "dwellingNumber": "102B",
    "postOfficeBoxText": "PostBox",
    "postOfficeBoxNumber": 1241
  },
  "contacts": {
    "telephone": "+41781254153",
    "telefax": "+41781254154",
    "mobile": "+41781254156",
    "email": "john.doe@adnovum.ch"
  },
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "remarks": "This is the new test user john doe",
  "modificationComment": "He lives in ZH"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/users/4254

User

Get user
GET/{clientExtId}/users/{extId}

Returns the user with the given external ID, belonging to the client with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.UserView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1000
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1000",
  "clientExtId": "1000",
  "userState":"active",
  "version":0,
  "loginId":"testUser",
  "languageCode":"en",
  "isTechnicalUser":false,
  "name":{
    "title":"Mr.",
    "firstName":"John",
    "familyName":"Doe"
  },
  "sex":"male",
  "gender":"male",
  "birthDate":"1969-04-12",
  "address":{
    "countryCode":"ch",
    "city":"Zurich",
    "postalCode":"123414",
    "addressline1":"PostBox 1241",
    "addressline2":"Company XYZ",
    "street":"Poststreet",
    "houseNumber":"12",
    "dwellingNumber":"102B",
    "postOfficeBoxText":"PostBox",
    "postOfficeBoxNumber":1241
  },
  "contacts":{
    "telephone":"+41781254153",
    "telefax":"+41781254154",
    "mobile":"+41781254156",
    "email":"john.doe@adnovum.ch"
  },
  "validity":{
    "from":"2016-12-31T12:00:00Z",
    "to":"2022-01-01T12:00:00Z"
  },
  "remarks":"This is test user john doe",
  "modificationComment":"Adjusted his address",
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z",
}

Delete user
DELETE/{clientExtId}/users/{extId}

Deletes the user with the given external ID, belonging to the client with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.UserDelete, AccessControl.UserDeleteTechUser (for deleting technical users only)

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1000
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the user.

Response  204

Update user
PATCH/{clientExtId}/users/{extId}

Updates the user with the given external ID, belonging to the client with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.UserView, AccessControl.UserModify, AccessControl.UserModifyTechUser (for modifying technical users only)

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1000
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "userState": "active",
  "version": 0,
  "loginId": "testUser",
  "languageCode": "en",
  "isTechnicalUser": false,
  "name": {
    "title": "Mr.",
    "firstName": "John",
    "familyName": "Doe"
  },
  "sex": "male",
  "gender": "male",
  "birthDate": "1969-04-12",
  "address": {
    "countryCode": "ch",
    "city": "Budapest",
    "postalCode": "123414",
    "addressline1": "PostBox 1241",
    "addressline2": "Company XYZ",
    "street": "Poststreet",
    "houseNumber": "12",
    "dwellingNumber": "102B",
    "postOfficeBoxText": "PostBox",
    "postOfficeBoxNumber": 1241
  },
  "contacts": {
    "telephone": "+41781234567",
    "telefax": "+41781254154",
    "mobile": "+41781254156",
    "email": "john.doe@adnovum.ch"
  },
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "remarks": "This is test user john doe",
  "modificationComment": "Adjusted his telephone number"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "extId": "1000",
 "clientExtId": "1000",
 "userState":"active",
  "version":1,
  "loginId":"testUser",
 "languageCode":"en",
  "isTechnicalUser":false,
  "name":{
  "title":"Mr.",
  "firstName":"John",
  "familyName":"Doe"
 },
 "sex":"male",
 "gender":"male",
 "birthDate":"1969-04-12",
 "address":{
  "countryCode":"ch",
  "city":"Budapest",
  "postalCode":"123414",
  "addressline1":"PostBox 1241",
  "addressline2":"Company XYZ",
  "street":"Poststreet",
  "houseNumber":"12",
   "dwellingNumber":"102B",
   "postOfficeBoxText":"PostBox",
   "postOfficeBoxNumber":1241
  },
  "contacts":{
    "telephone":"+41781234567",
    "telefax":"+41781254154",
   "mobile":"+41781254156",
   "email":"john.doe@adnovum.ch"
 },
 "validity":{
  "from":"2016-12-31T12:00:00Z",
  "to":"2022-01-01T12:00:00Z"
 },
 "remarks":"This is test user john doe",
 "modificationComment":"Adjusted his telephone number"
 "created": "2018-04-24T14:22:20Z",
 "lastModified": "2018-04-24T14:22:20Z"
}

Properties experimental

Get properties
GET/{clientExtId}/users/{extId}/properties/

Returns all properties of the user with the given external ID, as an object of key-value pairs. If there are no properties found, an empty object is returned. Properties are additional, customer-specific attributes of an entity.

Required permissions

AccessControl.UserView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1000/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "propertyKey1" : "propertyValue1",
 "propertyKey2" : "propertyValue2",
}

Update user properties experimental
PATCH/{clientExtId}/users/{extId}/properties/

Updates the properties of the user with the given external ID, belonging to the client with the given external ID. The body must contain an object of key-value property pairs.

Required permissions

AccessControl.UserView, AccessControl.UserModify, AccessControl.PropertyValueCreate, AccessControl.PropertyValueDelete, AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1000/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey2": "propertyValue2",
  "propertyKey3": "propertyNewValue3"
}

User profiles

Get user profiles
GET/{clientExtId}/users/{extId}/profiles/

Returns all profiles of the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.UserView, AccessControl.ProfileView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/100/profiles/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 100

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "1002",
      "userExtId": "100",
      "unitExtId": "200",
      "clientExtId": "1000",
      "deputedProfileExtId": "8566",
      "profileState": "active",
      "version": 0,
      "name": "something",
      "isDefaultProfile": true,
      "remarks": "something",
      "modificationComment": "none",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    },
    {
      "extId": "1001",
      "userExtId": "100",
      "unitExtId": "200",
      "clientExtId": "1000",
      "deputedProfileExtId": "8566",
      "profileState": "active",
      "version": 0,
      "name": "something2",
      "isDefaultProfile": true,
      "remarks": "something2",
      "modificationComment": "none",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1524579740_1001",
    "limit": 100
  }
}

Create user profile
POST/{clientExtId}/users/{extId}/profiles/

Creates a new profile for the user with the given external ID.

since 2.71

Required permissions

AccessControl.ProfileCreate, AccessControl.AuthorizationCreate (for creating non-technical users only)

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/100/profiles/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 100

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1003",
  "unitExtId": "200",
  "deputedProfileExtId": "8566",
  "profileState": "active",
  "version": 0,
  "name": "something3",
  "isDefaultProfile": true,
  "remarks": "something3",
  "modificationComment": "none"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/profiles/1003

User archive

Archive user
POST/{clientExtId}/users/{extId}/archive/

Archives an existing user with the given external ID. All the profiles of the user are archived and the credentials are deleted.

since 2.73

Required permissions

AccessControl.UserView, AccessControl.UserArchive, AccessControl.UserArchiveTechUser (for archiving technical users only)

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1000/archive/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the user.

Response  204

Consents

Create consent
POST/{clientExtId}/users/{extId}/consents/

Creates a consent by accepting terms for a user determined by its client external ID and user external ID. The accepted terms are determined by the terms external ID provided in the request body.

since 2.75.1

Required permissions

AccessControl.ConsentCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1000/consents/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "termsExtId": "1001"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/users/1000/consents/1001

Pending terms

Get pending terms
GET/users/terms-pending/

Gets all the terms for a user for which there is no consent given for the current version yet (or silent acceptance is not true).

since 2.75.1

Required permissions

AccessControl.ConsentView, AccessControl.TermsView

Example URI

GET https://your-host/nevisidm/api/core/v1/users/terms-pending/
Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "8865",
      "name": "Terms and conditions",
      "active": true,
      "silentAcceptance": false,
      "termsVersion": "1.0",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z",
      "urls": {
        "es": "https://www.sampleUrl.terms",
        "it": "https://www.sampleUrl2.terms"
      },
      "applicationExtIds": [
        "10101",
        "20202"
      ]
    },
    {
      "extId": "8866",
      "name": "Terms and conditions for cats",
      "active": true,
      "silentAcceptance": true,
      "termsVersion": "1.1",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z",
      "urls": {
        "es": "https://www.sampleUrlA.terms",
        "it": "https://www.sampleUrlB.terms"
      },
      "applicationExtIds": [
        "11111",
        "22222"
      ]
    }
  ]
}

Profile REST Service

Profiles are connecting users with units, roles and enterprise roles.

A profile belongs to one user, and one user only, during its lifetime. A user can have zero to many profiles. Each profile is independent from each other. For example, suppose a user has the profiles A and B. If the user is logged in with profile A, the system will not consider the roles assigned to profile B.

A profile must belong to a unit. This unit can be freely changed.

It is possible to assign multiple roles and enterprise roles to a profile with PUT. Likewise, it is possible to unassign roles and enterprise roles from the profile with DELETE.

Authorizations are connector objects in the business model. They connect a given profile with a given role. Authorizations have some attributes that you can set through the nevisIDM REST API:

  • clientGlobal,

  • unitGlobal,

  • appGlobal, and

  • enterpriseRoleGlobal.

Enterprise authorizations are considered as special business objects. They connect a profile with an enterprise role.

Profile external IDs are unique per client only, not globally. Therefore, you must always set the target client.

Profile DTO

The profile DTO has the following fields:

  • extId - The external ID of the profile (read-only string).

  • userExtId - The external ID of the user to whom the profile belongs (read-only string).

  • unitExtId - The external ID of the unit to which the profile belongs (read-only string).

  • clientExtId - The external ID of the client to which the policy belongs (read-only string).

  • deputedProfileExtId - The external ID of the deputed profile (read-only string).

  • name - The name of the profile (string).

  • profileState - The state of the profile (string).

  • isDefaultProfile - Determines whether the profile is default or not (boolean).

  • remarks - Textual remark regarding the profile (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the profile (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Authorization DTO

The authorization DTO has the following fields:

  • extId - The external ID of the object.

  • roleExtId - The external ID of the connected role (read-only string).

  • clientGlobal - Determines whether the authorization is applicable for the whole client (boolean). You can set this attribute with the nevisIDM REST API.

  • unitGlobal - Determines whether the authorization is restricted to a unit (boolean). You can set this attribute with the nevisIDM REST API.

  • appGlobal - Determines whether the authorization is restricted to an application (boolean). You can set this attribute with the nevisIDM REST API.

  • enterpriseRoleGlobal - Determines whether the authorization is restricted to an enterprise role (boolean). You can set this attribute with the nevisIDM REST API.

  • validity - Describes the validity period of the authorization (object).

    • from - Start date of the authorization’s validity in ISO format (string).
    • to - End date of the authorization’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (string).

  • lastModified - Date when the entity was last modified (string).

Application DTO

The application DTO has the following fields:

  • extId - External ID of the application (read-only string).

  • name - Internal name of the application (string).

  • description - Textual description of the application (string).

  • url - URL of the application.

  • displayed - Determines whether the application must be displayed on nevisPortal (boolean).

  • displayName - Language-dependent name of the application (object).

    • EN - Application name in English (string).
    • DE - Application name in German (string).
    • FR - Application name in French (string).
    • IT - Application name in Italian (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Unit DTO

The unit DTO has the following fields:

  • extId - The external ID of the unit (read-only string).

  • parentUnitExtId - The external ID of the parent unit (read-only string).

  • clientExtId - The external ID of the client the unit belongs to (read-only string).

  • name - The name of the unit (string).

  • hierarchicalName - The path from the root unit to the actual unit. The external IDs of the units are concatenated with the “/” character (read-only string).

  • description - The textual description of the unit (string).

  • location - Free textual description of the physical location of the unit. Different departments of a company can be in different locations (string).

  • displayName - The language-dependent name of the unit (object).

    • EN - Unit name in English (string).
    • DE - Unit name in German (string).
    • FR - Unit name in French (string).
    • IT - Unit name in Italian (string).

  • abbreviation - The short form of the unit’s name (object).

    • EN - Abbreviation in English (string).
    • DE - Abbreviation in German (string).
    • FR - Abbreviation in French (string).
    • IT - Abbreviation in Italian (string).

  • profileless - Determines whether profile assignment is allowed (boolean).

  • validity - The validity period of the unit entity (object).

    • from - The start date of the unit’s validity period in ISO format (string).
    • to - The end date of the unit’s validity period in ISO format (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Enterprise Authorization DTO

The enterprise authorization DTO has the following fields:

  • extId - The external ID of the object.

  • enterpriseRoleExtId - The external ID of the enterprise role (read-only string).

  • validity - Describes the validity period of the authorization (object).

    • from - Start date of the authorization’s validity in ISO format (string).
    • to - End date of the authorization’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (string).

  • lastModified - Date when the entity was last modified (string).

Enterprise role DTO

The enterprise role DTO has the following fields:

  • extId - The external ID of the enterprise role (string).

  • clientExtId - The external ID of the client to which the enterprise role belongs (string).

  • name - The name of the enterprise role (string).

  • description - The textual description of the enterprise role (string).

  • displayName - The language-dependent name of the enterprise role (object).

    • EN - The enterprise role name in English (string).
    • DE - The enterprise role name in German (string).
    • FR - The enterprise role name in French (string).
    • IT - The enterprise role name in Italian (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (string).

  • lastModified - The date when the entity was last modified (string).

Profile

Get profile
GET/{clientExtId}/profiles/{extId}

Returns the profile with the given external ID, belonging to the client with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.ProfileView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1001",
  "userExtId": "1012",
  "unitExtId": "1000",
  "clientExtId": "1000",
  "deputedProfileExtId": "8566",
  "profileState": "active",
  "version": 0,
  "name": "something",
  "isDefaultProfile": true,
  "remarks": "something",
  "modificationComment": "none",
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
  "validity": {
    "from":"2016-12-31T12:00:00Z",
    "to":"2022-01-01T12:00:00Z"
  }
}

Update profile
PATCH/{clientExtId}/profiles/{extId}

Updates the profile with the given external ID, which belongs to the client with the given external ID.

since 2.71

Required permissions

AccessControl.ProfileView, AccessControl.ProfileModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/profiles/1001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "profileState": "active",
  "version": 1,
  "name": "something",
  "isDefaultProfile": true,
  "remarks": "something",
  "modificationComment": "new validity",
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2024-01-01T12:00:00Z"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1001",
  "userExtId": "1012",
  "unitExtId": "1000",
  "clientExtId": "1000",
  "deputedProfileExtId": "8566",
  "profileState": "active",
  "version": 2,
  "name": "something",
  "isDefaultProfile": true,
  "remarks": "something",
  "modificationComment": "new validity",
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2024-01-01T12:00:00Z"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Delete profile
DELETE/{clientExtId}/profiles/{extId}

Deletes the profile with the given external ID, belonging to the client with the given external ID.

since 2.71

Required permissions

AccessControl.ProfileDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/profiles/1001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Response  204

Authorizations

Create authorization
POST/{clientExtId}/profiles/{extId}/authorizations/

Creates a new authorization for the profile with the given external ID. This operation assigns the role defined in the request to the target profile.

since 2.71

Required permissions

AccessControl.AuthorizationCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1001",
  "roleExtId": "1002",
  "clientGlobal": true,
  "unitGlobal": true,
  "appGlobal": true,
  "enterpriseRoleGlobal": true,
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  }
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/1001

Get authorizations
GET/{clientExtId}/profiles/{extId}/authorizations/

Returns all authorizations of the profile with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.AuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "2002",
      "roleExtId": "1001",
      "version": 0,
      "clientGlobal": true,
      "unitGlobal": true,
      "appGlobal": true,
      "enterpriseRoleGlobal": true,
      "validity": {
        "from": "2016-12-31T12:00:00Z",
        "to": "2022-01-01T12:00:00Z"
      },
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    },
    {
      "extId": "2001",
      "roleExtId": "1000",
      "version": 0,
      "clientGlobal": true,
      "unitGlobal": true,
      "appGlobal": true,
      "enterpriseRoleGlobal": true,
      "validity": {
        "from": "2016-12-31T12:00:00Z",
        "to": "2022-01-01T12:00:00Z"
      },
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1524579739_2001",
    "limit": 100
  }
}

Authorization

Get authorization
GET/{clientExtId}/profiles/{profileExtId}/authorizations/{extId}

Returns the authorization with the given external ID, belonging to the profile with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.AuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/2001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 2001

ExtID of the authorization.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2001",
  "roleExtId": "1001",
  "version": 0,
  "clientGlobal": true,
  "unitGlobal": true,
  "appGlobal": true,
  "enterpriseRoleGlobal": true,
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Update authorization
PATCH/{clientExtId}/profiles/{profileExtId}/authorizations/{extId}

Updates an authorization with the given external ID.

since 2.71

Required permissions

AccessControl.AuthorizationView, AccessControl.AuthorizationModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/2001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 2001

ExtID of the authorization.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "version": 2,
  "clientGlobal": true,
  "unitGlobal": true,
  "appGlobal": false,
  "enterpriseRoleGlobal": true,
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2001",
  "roleExtId": "1001",
  "version": 3,
  "clientGlobal": true,
  "unitGlobal": true,
  "appGlobal": false,
  "enterpriseRoleGlobal": true,
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Delete authorization
DELETE/{clientExtId}/profiles/{profileExtId}/authorizations/{extId}

Deletes the authorization with the given external ID.

since 2.71

Required permissions

AccessControl.AuthorizationDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/2001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 2001

ExtID of the authorization.

Response  204

Authorization properties experimental

Get properties
GET/{clientExtId}/profiles/{profileExtId}/authorizations/{extId}/properties

Returns all properties of the authorization with the given external ID, as an object of key-value pairs. Properties with the scope onProfileForAppGlobal will be overridden by properties with the scope onProfileForApp, in case properties have the same key, that is, the same property name. Properties are additional, customer-specific attributes of an entity.

Required permissions

AccessControl.AuthorizationView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/2001/properties
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 2001

ExtID of the authorization.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyValue1",
  "propertyKey2": "propertyValue2"
}

Update properties
PATCH/{clientExtId}/profiles/{profileExtId}/authorizations/{extId}/properties

Updates the properties of the authorization with the given external ID. The body must contain an object with key-value property pairs.

Required permissions

AccessControl.ProfileView, AccessControl.ProfileModify, AccessControl.PropertyValueCreate, AccessControl.PropertyValueModify, AccessControl.PropertyValueDelete, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/2001/properties
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 2001

ExtID of the authorization.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3",
  "propertyKey4": ""
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey2": "propertyValue2",
  "propertyKey3": "propertyNewValue3"
}

Enterprise authorizations

Create enterprise authorization
POST/{clientExtId}/profiles/{profileExtId}/eauthorizations/

Creates a new enterprise authorization for the profile with the given external ID. This operation assigns the enterprise role defined in the request to the target profile.

since 2.75.2

Required permissions

AccessControl.EnterpriseAuthorizationCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eauthorizations/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1020",
  "enterpriseRoleExtId": "1002",
  "validity": {
    "from":"2016-12-31T12:00:00Z",
    "to":"2022-01-01T12:00:00Z"
  },
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eauthorizations/1020

Get enterprise authorizations
GET/{clientExtId}/profiles/{profileExtId}/eauthorizations/

Returns all enterprise authorizations of the profile with the given external ID.

since 2.75.2
Selfadmin

Required permissions

AccessControl.EnterpriseAuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eauthorizations/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "2001",
      "enterpriseRoleExtId": "1001",
      "version": 0,
      "validity": {
        "from": "2016-12-31T12:00:00Z",
        "to": "2022-01-01T12:00:00Z"
      },
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    },
    {
      "extId": "2002",
      "enterpriseRoleExtId": "1000",
      "version": 0,
      "validity": {
        "from": "2016-12-31T12:00:00Z",
        "to": "2022-01-01T12:00:00Z"
      },
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1524579740_2002",
    "limit": 100
  }
}

Enterprise authorization

Get enterprise authorization
GET/{clientExtId}/profiles/{profileExtId}/eauthorizations/{extId}

Returns the enterprise authorization with the given external ID, which belongs to the profile with the given external ID.

since 2.75.2
Selfadmin

Required permissions

AccessControl.EnterpriseAuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eauthorizations/2001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 2001

ExtID of the enterprise authorization.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2001",
  "enterpriseRoleExtId": "1001",
  "version": 1,
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Update enterprise authorization
PATCH/{clientExtId}/profiles/{profileExtId}/eauthorizations/{extId}

Updates the enterprise authorization with the given external ID.

since 2.75.2

Required permissions

AccessControl.EnterpriseAuthorizationView, AccessControl.EnterpriseAuthorizationModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eauthorizations/2001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 2001

ExtID of the enterprise authorization.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "version": 1,
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2024-01-01T12:00:00Z"
  }
}
Response  200
HideShow

When an enterprise authorization exists with the given external ID, the response looks like this:

Headers
Content-Type: application/json
Body
{
  "extId": "2001",
  "enterpriseRoleExtId": "1001",
  "version": 2,
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2024-01-01T12:00:00Z"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Delete enterprise authorization
DELETE/{clientExtId}/profiles/{profileExtId}/eauthorizations/{extId}

Deletes the enterprise authorization with the given external ID.

since 2.75.2

Required permissions

AccessControl.EnterpriseAuthorizationDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eauthorizations/2001
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 2001

ExtID of the enterprise authorization.

Response  204

Profile roles

Get profile roles
GET/{clientExtId}/profiles/{extId}/roles

Returns all roles of the profile with the given external ID, including roles assigned over the enterprise roles.

since 2.71
Selfadmin

Required permissions

AccessControl.AuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/roles
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "2011",
      "applicationExtId": "1000",
      "applicationName": "Confluence",
      "version": 0,
      "name": "regularRole",
      "description": "role of normal users",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    },
    {
      "extId": "2033",
      "applicationExtId": "1000",
      "applicationName": "Confluence",
      "version": 0,
      "name": "adminRole",
      "description": "role of admins",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1524579740_2033",
    "limit": 100
  }
}

Profile enterprise roles

Get profile eroles
GET/{clientExtId}/profiles/{extId}/eroles

Returns all enterprise roles of the profile with the given external ID.

since 2.75.2
Selfadmin

Required permissions

AccessControl.EnterpriseAuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eroles
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "2031",
      "clientExtId": "1000",
      "version": 1,
      "name": "erole1",
      "description": "erole1",
      "displayName": {
        "EN": "erole1",
        "DE": "erole1",
        "FR": "erole1",
        "IT": "erole1"
      },
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    },
    {
      "extId": "2034",
      "clientExtId": "1000",
      "version": 3,
      "name": "erole2",
      "description": "erole2",
      "displayName": {
        "EN": "erole2",
        "DE": "erole2",
        "FR": "erole2",
        "IT": "erole2"
      },
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:24:20Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1524579740_2034",
    "limit": 100
  }
}

Profile unit

Get unit
GET/{clientExtId}/profiles/{extId}/unit

Returns the unit of the profile with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.ProfileView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/unit
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1000",
  "parentUnitExtId": "2311",
  "clientExtId": "1000",
  "version": 0,
  "hierarchicalName": "2311/1000",
  "name": "MyUnit1",
  "location": "something",
  "description": "something",
  "displayName": {
    "EN": "MyUnit1",
    "DE": "MyUnit1",
    "FR": "MyUnit1",
    "IT": "MyUnit1"
  },
  "abbreviation": {
    "EN": "MU1",
    "DE": "MU1",
    "FR": "MU1",
    "IT": "MU1"
  },
  "profileless": false,
  "modificationComment": "blabla",
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Profile unit

Assign unit
PUT/{clientExtId}/profiles/{profileExtId}/unit/{extId}

Replaces the actual unit assignment of the profile with the given external ID, by the unit with the given external ID.

since 2.71

Required permissions

AccessControl.UnitView, AccessControl.ProfileModify

Example URI

PUT https://your-host/nevisidm/api/core/v1/1000/profiles/1001/unit/1002
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

profileExtId
string (required) Example: 1001

ExtID of the profile.

extId
string (required) Example: 1002

ExtID of the unit to be assigned.

Response  204

Profile applications

Get applications
GET/{clientExtId}/profiles/{extId}/applications

Returns all applications that are authorized to be used by the profile with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.ApplicationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/applications
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "1000",
      "version": 10,
      "name": "Confluence",
      "description": "Confluence is used to store documents.",
      "url": "www.example.com/confluence/",
      "displayed": true,
      "displayName": {
        "EN": "Confluence",
        "DE": "Confluence",
        "FR": "Confluence",
        "IT": "Confluence"
      },
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    },
    {
      "extId": "1001",
      "version": 0,
      "name": "Jira",
      "description": "Jira is for ticketing.",
      "url": "www.example.com/Jira/",
      "displayed": true,
      "displayName": {
        "EN": "Jira",
        "DE": "Jira",
        "FR": "Jira",
        "IT": "Jira"
      },
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1524579740_1001",
    "limit": 100
  }
}

Profile properties experimental

Get properties
GET/{clientExtId}/profiles/{extId}/properties

Returns all properties of the profile with the given external ID, as an object of key-value pairs. If there are no properties found, an empty object is returned. Properties are additional, customer-specific attributes of an entity.

Required permissions

AccessControl.ProfileView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/properties
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "propertyKey1" : "propertyValue1",
 "propertyKey2" : "propertyValue2",
}

Update profile properties
PATCH/{clientExtId}/profiles/{extId}/properties

Updates the properties of the profile with the given external ID, belonging to the client with the given external ID. The body must contain an object of key-value property pairs.

Required permissions

AccessControl.ProfileView, AccessControl.ProfileModify, AccessControl.PropertyValueCreate, AccessControl.PropertyValueModify, AccessControl.PropertyValueDelete, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/profiles/1001/properties
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1001

ExtID of the profile.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1" : "propertyNewValue1",
  "propertyKey2" : "propertyValue2",
  "propertyKey3" : "propertyNewValue3",
}

Role REST Service

A role represents the set of permissions of a user.

A role belongs to one application and one application only during its entire lifetime. As applications can be assigned to many clients, the external ID of a role is unique in the whole system. This enables the caller to obtain a specific role resource and to modify its fields.

Only the name and description of a role are modifiable. Therefore, modification of a role’s fields does not have any impact on the accessibility of the corresponding application.

Note that deleting a role implies its permanent removal from all profiles and enterprise roles.

Role DTO

The role DTO has the following fields:

  • extId - The external ID of the role (read-only string).

  • applicationExtId - The external ID of the application the role belongs to (string).

  • applicationName - The name of the application the role belongs to (string).

  • name - The name of the role (string).

  • description - The textual description of the role (string).

  • version - The version used for optimistic locking (number).

  • created - The creation date of the entity (read-only string).

  • lastModified - The date when the entity was last modified (string).

Role

Get role
GET/roles/{extId}

Returns the role with the given external ID.

since 2.71

Required permissions

AccessControl.RoleView

Example URI

GET https://your-host/nevisidm/api/core/v1/roles/231
URI Parameters
HideShow
extId
string (required) Example: 231

ExtID of the role.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "231",
  "applicationExtId": "1000",
  "applicationName": "Confluence",
  "version": 1,
  "name": "regularRole",
  "description": "role of normal users",
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Update role
PATCH/roles/{extId}

Updates the role with the given external ID.

since 2.74

Required permissions

AccessControl.RoleView, AccessControl.RoleModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/roles/231
URI Parameters
HideShow
extId
string (required) Example: 231

ExtID of the role.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "version": 1,
  "name": "regularRole",
  "description": "regular role of normal users"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "231",
  "applicationExtId": "1000",
  "applicationName": "Confluence",
  "version": 2,
  "name": "regularRole",
  "description": "regular role of normal users",
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Delete role
DELETE/roles/{extId}

Deletes the role with the given external ID.

since 2.74

Required permissions

AccessControl.RoleDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/roles/231
URI Parameters
HideShow
extId
string (required) Example: 231

ExtID of the role.

Response  204

Properties

Get properties
GET/roles/{extId}/properties

Returns all properties of the role with the given external ID, as an object of key-value pairs. Properties are additional, customer-specific attributes of an entity.

since 2.74

Required permissions

AccessControl.RoleView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/roles/232/properties
URI Parameters
HideShow
extId
string (required) Example: 232

ExtID of the role.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyValue1",
  "propertyKey2": "propertyValue2"
}

Update role properties
PATCH/roles/{extId}/properties

Updates the properties of a role with given external ID of the role. The body must contain an object of of key-value property pairs.

since 2.74

Required permissions

AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView, AccessControl.PropertyValueCreate, AccessControl.PropertyValueModify, AccessControl.PropertyValueDelete

Example URI

PATCH https://your-host/nevisidm/api/core/v1/roles/232/properties
URI Parameters
HideShow
extId
string (required) Example: 232

ExtID of the role.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "propertyKey1" : "propertyNewValue1",
 "propertyKey2" : "propertyValue2",
 "propertyKey3" : "propertyNewValue3",
}

Unit REST Service

Units represent the organizational structure of a client. A unit always belongs to exactly one client; it is not possible to change this client during the unit’s lifetime. A unit can have a parent unit (except for root units). User profiles assigned to a certain unit represent the people that belong to this unit in accordance with the corporate organization.

Unit external IDs are unique per client only. Therefore, you must always set the target client.

Note that retrieval of only the root units of a client is not supported yet. The planned solution is to implement the following filter: “GET /clients/{extId}/units/”.

Unit DTO

The unit DTO has the following fields:

  • extId - The external ID of the unit (read-only string).

  • parentUnitExtId - The external ID of the parent unit (read-only string).

  • clientExtId - The external ID of the client the unit belongs to (read-only string).

  • name - The name of the unit (string).

  • hierarchicalName - The path from the root unit to the actual unit. The external IDs of the units are concatenated with the “/” character (read-only string).

  • description - The textual description of the unit (string).

  • location - Free textual description of the physical location of the unit. Different departments of a company can be in different locations (string).

  • displayName - The language-dependent name of the unit (object).

    • EN - Unit name in English (string).
    • DE - Unit name in German (string).
    • FR - Unit name in French (string).
    • IT - Unit name in Italian (string).

  • abbreviation - The short form of the unit’s name (object).

    • EN - Abbreviation in English (string).
    • DE - Abbreviation in German (string).
    • FR - Abbreviation in French (string).
    • IT - Abbreviation in Italian (string).

  • profileless - Determines whether profile assignment is allowed (boolean).

  • validity - The validity period of the unit entity (object).

    • from - The start date of the unit’s validity period in ISO format (string).
    • to - The end date of the unit’s validity period in ISO format (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Units

Create unit
POST/{clientExtId}/units/

Creates a new unit for the client with the given external ID.

since 2.73

Required permissions

AccessControl.UnitCreate, AccessControl.UnitCreateTopUnit (if no parent unit parentUnitExtId is provided)

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/units/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1000",
  "name": "MyUnit1",
  "location": "something",
  "description": "something",
  "displayName": {
    "EN": "MyUnit1",
    "DE": "MyUnit1",
    "FR": "MyUnit1",
    "IT": "MyUnit1"
  },
  "abbreviation": {
    "EN": "MU1",
    "DE": "MU1",
    "FR": "MU1",
    "IT": "MU1"
  },
  "profileless": false,
  "modificationComment": "blabla"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/units/1000

Unit

Get unit
GET/{clientExtId}/units/{extId}

Returns the unit with the given external ID, which belongs to the client with the given external ID.

Required permissions

AccessControl.UnitView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/units/1000
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the unit.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1000",
  "parentUnitExtId": "2311",
  "clientExtId": "1000",
  "version": 10,
  "hierarchicalName": "2023/2311/1000",
  "name": "MyUnit1",
  "location": "something",
  "description": "something",
  "displayName": {
    "EN": "MyUnit1",
    "DE": "MyUnit1",
    "FR": "MyUnit1",
    "IT": "MyUnit1"
  },
  "abbreviation": {
    "EN": "MU1",
    "DE": "MU1",
    "FR": "MU1",
    "IT": "MU1"
  },
  "profileless": false,
  "modificationComment": "blabla",
  "validity": {
    "from": "2100-01-01T00:00:00Z",
    "to": "2200-01-01T00:00:00Z"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Delete unit
DELETE/{clientExtId}/units/{extId}

Deletes the unit with the given external ID, which belongs to the client with the given external ID.

since 2.73

Required permissions

AccessControl.UnitDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/units/1000
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the unit.

Response  204

Update unit
PATCH/{clientExtId}/units/{extId}

Updates the unit with the given external ID, belonging to the client with the given external ID.

since 2.73

Required permissions

AccessControl.UnitView, AccessControl.UnitModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/units/1000
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the unit.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "version": 1,
  "name": "MyUnit1",
  "location": "zurich",
  "description": "something",
  "displayName": {
    "EN": "MyUnit1",
    "DE": "MyUnit1",
    "FR": "MyUnit1",
    "IT": "MyUnit1"
  },
  "abbreviation": {
    "EN": "MU1",
    "DE": "MU1",
    "FR": "MU1",
    "IT": "MU1"
  },
  "profileless": false,
  "modificationComment": "blabla"
}
Response  200
HideShow

If a unit exists with the given external ID, the response looks as follows:

Headers
Content-Type: application/json
Body
{
  "extId": "1000",
  "parentUnitExtId": "2311",
  "clientExtId": "1000",
  "version": 2,
  "hierarchicalName": "2023/2311/1000",
  "name": "MyUnit1",
  "location": "zurich",
  "description": "something",
  "displayName": {
    "EN": "MyUnit1",
    "DE": "MyUnit1",
    "FR": "MyUnit1",
    "IT": "MyUnit1"
  },
  "abbreviation": {
    "EN": "MU1",
    "DE": "MU1",
    "FR": "MU1",
    "IT": "MU1"
  },
  "profileless": false,
  "modificationComment": "blabla",
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Child units experimental

Get children experimental
GET/{clientExtId}/units/{extId}/children

Returns all children of the unit with the given external ID.

Required permissions

AccessControl.UnitView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/units/1000/children
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the unit.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "1001",
      "parentUnitExtId": "1000",
      "clientExtId": "1000",
      "version": 1,
      "hierarchicalName": "2023/2311/1000/1001",
      "name": "MyUnit01",
      "location": "something",
      "description": "something",
      "displayName": {
        "EN": "MyUnit01",
        "DE": "MyUnit01",
        "FR": "MyUnit01",
        "IT": "MyUnit01"
      },
      "abbreviation": {
        "EN": "MU01",
        "DE": "MU01",
        "FR": "MU01",
        "IT": "MU01"
      },
      "profileless": true,
      "modificationComment": "blabla",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    },
    {
      "extId": "1002",
      "parentUnitExtId": "1000",
      "clientExtId": "1000",
      "version": 1,
      "hierarchicalName": "2023/2311/1000/1002",
      "name": "MyUnit02",
      "location": "something",
      "description": "something",
      "displayName": {
        "EN": "MyUnit02",
        "DE": "MyUnit02",
        "FR": "MyUnit02",
        "IT": "MyUnit02"
      },
      "abbreviation": {
        "EN": "MU02",
        "DE": "MU02",
        "FR": "MU02",
        "IT": "MU02"
      },
      "profileless": true,
      "modificationComment": "blabla",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1524579740_1002",
    "limit": 100
  }
}

Child Unit experimental

Assign child unit
PUT/{clientExtId}/units/{extId}/children/{childExtId}

Moves the child unit with the given external ID childExtId under the parent unit with the given external ID extId.

Required permissions

AccessControl.UnitModify

Example URI

PUT https://your-host/nevisidm/api/core/v1/1000/units/1000/children/1003
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the parent unit.

childExtId
string (required) Example: 1003

ExtID of the child unit.

Response  204

Unassign child unit
DELETE/{clientExtId}/units/{extId}/children/{childExtId}

Removes the child unit with the given external ID childExtId from the parent unit with the given external ID extId. This action makes the child unit a root unit.

Required permissions

AccessControl.UnitModify, AccessControl.UnitCreateTopUnit

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/units/1000/children/1003
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the parent unit.

childExtId
string (required) Example: 1003

ExtID of the child unit.

Response  204

Properties experimental

Get properties experimental
GET/{clientExtId}/units/{extId}/properties/

Returns all properties of the unit with the given external ID, as an object of key-value pairs. Properties are additional, customer-specific attributes of an entity.

Required permissions

AccessControl.UnitView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/units/1000/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the unit.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "propertyKey1" : "propertyValue1",
 "propertyKey2" : "propertyValue2",
}

Update unit properties experimental
PATCH/{clientExtId}/units/{extId}/properties/

Updates the properties of the unit with the given external ID, belonging to the client with the given external ID. The body must contain an object of key-value property pairs.

Required permissions

AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView, AccessControl.PropertyValueCreate, AccessControl.PropertyValueDelete, AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/units/1000/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 1000

ExtID of the unit.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "",
  "propertyKey3": "propertyNewValue3"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "propertyKey2" : "propertyValue2",
 "propertyKey3" : "propertyNewValue3",
}

Enterprise Role REST Service

An enterprise role defines a specific set of roles, for example, for people with the same business function. It can be assigned to multiple users’ profiles. This way, all users with the same enterprise role have the same included roles. Adding a role to or removing a role from a particular enterprise role will affect all assigned users - which can be hundreds of thousands of users in some cases. Therefore, use this service carefully.

Creating an enterprise role does not provide any additional access, because it is empty. Changing the enterprise role entity does not affect accessibility either.

You can only assign existing roles to an enterprise role, with PUT. If the role you want to assign does not exist yet, you must create it first through the Role REST Service. Roles can be unassigned with DELETE. Note that unassignment does not remove the role from the system.

Enterprise role external IDs are unique per client only, not globally. Therefore, you must always set the target client.

Enterprise role DTO

The enterprise role DTO has the following fields:

  • extId - The external ID of the enterprise role (string).

  • clientExtId - The external ID of the client to which the enterprise role belongs (string).

  • name - The name of the enterprise role (string).

  • description - The textual description of the enterprise role (string).

  • displayName - The language-dependent name of the enterprise role (object).

    • EN - The enterprise role name in English (string).
    • DE - The enterprise role name in German (string).
    • FR - The enterprise role name in French (string).
    • IT - The enterprise role name in Italian (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (string).

  • lastModified - The date when the entity was last modified (string).

Role DTO

The role DTO has the following fields:

  • extId - The external ID of the role (read-only string).

  • applicationExtId - The external ID of the application the role belongs to (string).

  • applicationName - The name of the application the role belongs to (string).

  • name - The name of the role (string).

  • description - The textual description of the role (string).

  • version - The version used for optimistic locking (number).

  • created - The creation date of the entity (read-only string).

  • lastModified - The date when the entity was last modified (string).

Enterprise roles

Create enterprise role
POST/{clientExtId}/eroles/

Creates a new enterprise role for the client with the given external ID.

since 2.75.2

Required permissions

AccessControl.EnterpriseRoleCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/eroles/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2345",
  "name": "erole1",
  "description": "erole1",
  "displayName": {
    "EN": "erole1",
    "DE": "erole1",
    "FR": "erole1",
    "IT": "erole1"
  }
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/eroles/2345

Enterprise role

Get enterprise role
GET/{clientExtId}/eroles/{eroleExtId}

Returns the enterprise role with the given external ID, belonging to the client with the given external ID.

since 2.75.2

Required permissions

AccessControl.EnterpriseRoleView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/eroles/2345
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

eroleExtId
string (required) Example: 2345

ExtID of the enterprise role.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2345",
  "clientExtId": "1000",
  "version": 1,
  "name": "erole1",
  "description": "erole1",
  "displayName": {
    "EN": "erole1",
    "DE": "erole1",
    "FR": "erole1",
    "IT": "erole1"
  },
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2017-08-17T00:00:00Z"
}

Update enterprise role
PATCH/{clientExtId}/eroles/{eroleExtId}

Updates the enterprise role with the given external ID, belonging to the client with the given external ID.

since 2.75.2

Required permissions

AccessControl.EnterpriseRoleView, AccessControl.EnterpriseRoleModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/eroles/2345
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

eroleExtId
string (required) Example: 2345

ExtID of the enterprise role.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "version": 2,
  "name": "erole1",
  "description": "erole1",
  "displayName": {
    "EN": "erole1",
    "DE": "erolle1",
    "FR": "erole1",
    "IT": "erole1"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2345",
  "clientExtId": "1000",
  "version": 3,
  "name": "erole1",
  "description": "erole1",
  "displayName": {
    "EN": "erole1",
    "DE": "erolle1",
    "FR": "erole1",
    "IT": "erole1"
  },
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2017-08-17T00:00:00Z"
}

Delete enterprise role
DELETE/{clientExtId}/eroles/{eroleExtId}

Deletes the enterprise role with the given external ID, belonging to the client with the given external ID.

since 2.75.2

Required permissions

AccessControl.EnterpriseRoleDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/eroles/2345
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

eroleExtId
string (required) Example: 2345

ExtID of the enterprise role.

Response  204

Enterprise role members

Get enterprise role members
GET/{clientExtId}/eroles/{eroleExtId}/roles

Returns all roles of the enterprise role with the given external ID.

since 2.75.2

Required permissions

AccessControl.RoleView, AccessControl.EnterpriseRoleView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/eroles/2345/roles
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

eroleExtId
string (required) Example: 2345

ExtID of the enterprise role.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "8865",
      "applicationExtId": "987",
      "applicationName": "Confluence",
      "version": 0,
      "name": "role1",
      "description": "role1",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    },
    {
      "extId": "2300",
      "applicationExtId": "987",
      "applicationName": "Confluence",
      "version": 0,
      "name": "role2",
      "description": "role2",
      "created": "2018-04-24T14:22:20Z",
      "lastModified": "2018-04-24T14:22:20Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1524579619_2300",
    "limit": 100
  }
}

Enterprise role member

Assign role
PUT/{clientExtId}/eroles/{eroleExtId}/roles/{roleExtId}

Assigns the role with the given external ID to the enterprise role with the given external ID.

since 2.75.2

Required permissions

AccessControl.EnterpriseRoleMemberCreate

Example URI

PUT https://your-host/nevisidm/api/core/v1/1000/eroles/2345/roles/2301
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

eroleExtId
string (required) Example: 2345

ExtID of the enterprise role.

roleExtId
string (required) Example: 2301

ExtID of the role.

Response  204

Unassign role
DELETE/{clientExtId}/eroles/{eroleExtId}/roles/{roleExtId}

Removes the role with the given external ID from the enterprise role with the given external ID.

since 2.75.2

Required permissions

AccessControl.EnterpriseRoleMemberDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/eroles/2345/roles/2301
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

eroleExtId
string (required) Example: 2345

ExtID of the enterprise role.

roleExtId
string (required) Example: 2301

ExtID of the role.

Response  204

Enterprise role properties

Get properties
GET/{clientExtId}/eroles/{eroleExtId}/properties/

Returns all properties of the enterprise role with the given external ID, as an object of key-value pairs. Properties are additional, customer-specific attributes of an entity.

since 2.75.2

Required permissions

AccessControl.EnterpriseRoleView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/eroles/2345/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

eroleExtId
string (required) Example: 2345

ExtID of the enterprise role.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyValue1",
  "propertyKey2": "propertyValue2"
}

Update properties
PATCH/{clientExtId}/eroles/{eroleExtId}/properties/

Updates the properties of an enterprise role with given external ID of the enterprise role. The body must contain an object of of key-value property pairs.

since 2.75.2

Required permissions

AccessControl.EnterpriseRoleView, AccessControl.EnterpriseRoleModify, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView, AccessControl.PropertyValueCreate, AccessControl.PropertyValueModify, AccessControl.PropertyValueDelete

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/eroles/2345/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

eroleExtId
string (required) Example: 2345

ExtID of the enterprise role.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
 "propertyKey1" : "propertyNewValue1",
 "propertyKey2" : "propertyValue2",
 "propertyKey3" : "propertyNewValue3",
}

Policy REST Service experimental

Policies are used to adjust the behavior and/or configuration of specific entities or components in nevisIDM (see also “Policy” in the nevisIDM reference guide). Policies describe for example the format of a credential or how a credential should work.

When you change a policy, the change comes into effect immediately. However, it does not affect the stored credentials. For example, if you change the minimum password length in the password policy from four to six characters, it is still possible to use an existing five-character password. But when you want to modify this password, you must select a new password that meets the currently valid policy.

A policy change has an impact on almost all users. Therefore, use this service carefully.

Policy external IDs are unique per client only, not globally. Therefore, you must always set the target client.

Policy DTO

The policy DTO has the following fields:

  • extId - The external ID of the policy (read-only string).

  • clientExtId - The external ID of the client to which the policy belongs (read-only string).

  • name - The name of the policy (string).

  • description - The textual description of the policy (string).

  • policyType - The type of policy (string).

  • defaultPolicy - Determines whether the policy is default or not (boolean).

  • parameters - Lists the policy parameters assigned to the policy configuration. The parameters are represented as name-value pairs (object).

  • version - The version used for optimistic locking (number).

  • created - The creation date of the entity (read-only string).

  • lastModified - The date when the entity was last modified (read-only string).

Policies

Create policy
POST/{clientExtId}/policies/

Creates a new policy for the client with the given external ID.

since 2.71

Required permissions

AccessControl.PolicyConfigurationCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/policies/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "99990049",
  "description": "PDF Email Policy",
  "name": "TicketPolicyForPDFEmailSending",
  "policyType": "TicketPolicy",
  "defaultPolicy": true,
  "version": 0,
  "parameters": {
    "param1": "value1",
    "param2": "value2",
    "paramN": "valueN"
  }
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/policies/99990049

Policy

Get policy
GET/{clientExtId}/policies/{extId}

Returns the policy with the given external ID, belonging to the client with the given external ID.

since 2.71

Required permissions

AccessControl.PolicyConfigurationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/policies/99990049
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 99990049

ExtID of the policy.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "99990049",
  "clientExtId": "1000",
  "description": "PDF Email Policy",
  "name": "TicketPolicyForPDFEmailSending",
  "policyType": "TicketPolicy",
  "defaultPolicy": true,
  "version": 0,
  "parameters": {
    "param1": "value1",
    "param2": "value2",
    "paramN": "valueN"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Delete policy
DELETE/{clientExtId}/policies/{extId}

Deletes the policy with the given external ID, belonging to the client with the given external ID.

since 2.71

Required permissions

AccessControl.PolicyConfigurationDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/policies/99990049
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 99990049

ExtID of the policy.

Response  204

Update policy
PATCH/{clientExtId}/policies/{extId}

Updates the policy with the given external ID, belonging to the client with the given external ID.

since 2.71

Required permissions

AccessControl.PolicyConfigurationView, AccessControl.PolicyConfigurationModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/policies/99990049
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 99990049

ExtID of the policy.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "description": "PDF Email Policy",
  "name": "TicketPolicyForPDFEmailSending",
  "policyType": "TicketPolicy",
  "defaultPolicy": true,
  "version": 0,
  "parameters": {
    "param1": "value1",
    "param2": "value2new",
    "paramN": "valueN"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "99990049",
  "clientExtId": "1000",
  "description": "PDF Email Policy",
  "name": "TicketPolicyForPDFEmailSending",
  "policyType": "TicketPolicy",
  "defaultPolicy": true,
  "version": 1,
  "parameters": {
    "param1": "value1",
    "param2": "value2new",
    "paramN": "valueN"
  },
  "created": "2018-04-24T14:22:20Z",
  "lastModified": "2018-04-24T14:22:20Z"
}

Password REST Service

The Password REST Service is the service for managing passwords. The service does not manage the password states: They have their own workflow.

Changing and deleting a user’s password can result in the loss of access to the system for the user. Creating and changing a password can also give a user additional access. Therefore, use this service carefully.

Note:

  • Password values are not exposed through GET, but can be set via POST (upon creation).

  • A password must always belong to a user. It cannot be reassigned to someone else.

Password external IDs are unique per client only, not globally. Therefore, you must always set the target client.

Password create DTO

The password create DTO has the following fields:

  • extId - The external ID of the password credential (string).

  • policyExtId - The external ID of the used password policy (string).

  • stateName - The state of the credential (string).

  • password - The value of the password credential. This field is never returned (string).

Password fragment DTO

The password fragment DTO represents the portion of the generated password that is returned to the caller. It has one field:

  • passwordFragment - A part of the generated password (string).

Password change DTO

The password change DTO has the following fields:

  • oldPassword - The old password. This field must be omitted when the caller changes the password of someone else (string).

  • newPassword - The new password to be set (string).

Password DTO

The Password DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • policyExtId - The external ID of the used policy (string).

  • resetCount - Number of times the credential was reset (number).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the password (string).

  • stateChangeDetail - Reason detail for the last state change of the password (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (password reset feature or administrator) (number).

  • lastFailedLoginDate - Date of last non-technical login failure, e.g., wrong password (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (password reset feature or administrator) (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the password (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

  • createdBy - The combination of the client name and login ID of the user who created the password (read-only string, not available in self admin).

  • modifiedBy - The combination of the client name and login ID of the user who last modified the password (read-only string, not available in self admin).

  • lastChangeDate - Date when the password was modified last time (read-only string, not available in self admin).

Password patch DTO

The password patch DTO has the following fields:

  • stateName - The state of the credential (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

Password

Create password
POST/{clientExtId}/users/{userExtId}/password

Creates a password for the user with the given external ID. No content is returned when in the given password policy the “Reset code” function is disabled (parameter resetCodeEnabled is set to false), or the length of the returned part of the reset code is set to “0” (parameter resetCodeLen0). In all other cases, the response will contain a part of the generated password, in the field passwordFragment.

since 2.71

Required permissions

AccessControl.CredentialCreate, AccessControl.PolicyConfigurationView, AccessControl.CredentialChangeState (if the state of the password is provided, through the stateName field)

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/password
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1001",
  "policyExtId": "100",
  "stateName": "active",
  "password": "secretpassword"
}
Response  204
HideShow
Headers
Content-Type: application/json
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "passwordFragment": "A31S@ass"
}

Get Password
GET/{clientExtId}/users/{userExtId}/password

Gets the password credential of the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialView

Technical fields limitation

Fields createdBy and modifiedBy hold the login id of the user when he created/modified the password. This login id might differ from the current login id of the user.

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/password
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2001",
  "userExtID": "1234",
  "policyExtId": "201",
  "resetCount": 0,
  "stateName": "active",
  "stateChangeReason": "changed-by-user",
  "lastSuccessfulLoginDate": "2018-10-26T11:27:24Z",
  "successfulLoginCount": 250,
  "lastFailedLoginDate": "2018-09-10T08:30:00Z",
  "failedLoginCount": 10,
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2018-01-11T12:30:00Z",
  "modificationComment": "string",
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2018-12-31T00:00:00Z"
  },
  "version": 3,
  "type": "PASSWORD",
  "createdBy": "loginId",
  "modifiedBy": "loginId",
  "lastChangeDate": "2017-08-17T00:00:00Z"
}

Update Password
PATCH/{clientExtId}/users/{userExtId}/password

Updates the password credential of the user with the given external ID.

since 2.71

Required permissions

AccessControl.CredentialView, AccessControl.CredentialModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/password
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
 "stateName": "active",
 "modificationComment": "modified",
 "version": 0,
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2001",
  "userExtID": "1234",
  "policyExtId": "201",
  "resetCount": 0,
  "stateName": "active",
  "stateChangeReason": "changed-by-user",
  "lastSuccessfulLoginDate": "2018-10-26T11:27:24Z",
  "successfulLoginCount": 250,
  "lastFailedLoginDate": "2018-09-10T08:30:00Z",
  "failedLoginCount": 10,
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2018-01-11T12:30:00Z",
  "modificationComment": "modified",
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2018-12-31T00:00:00Z"
  },
  "version": 0,
  "type": "PASSWORD",
  "createdBy": "loginId",
  "modifiedBy": "loginId",
  "lastChangeDate": "2017-08-17T00:00:00Z"
}

Delete Password
DELETE/{clientExtId}/users/{userExtId}/password

Deletes the password credential of the user with the given external ID.

since 2.73

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/password
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  204
HideShow
Headers
Content-Type: application/json

Password Change

Change Password
POST/{clientExtId}/users/{userExtId}/password/change

Changes the password of the user with the given external ID. The oldPassword field in the request body is mandatory if a caller wants to change his own password. In case the caller wants to change the password of another user, the oldPassword field in the request body must be omitted.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialModify, AccessControl.PolicyConfigurationView

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/password/change
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "oldPassword": "oldPassword",
  "newPassword": "newSecretPassword"
}
Response  204
HideShow
Headers
Content-Type: application/json

Password Reset experimental

Reset Password
POST/{clientExtId}/users/{userExtId}/password/reset

Resets the password of the user with the given external ID. Depending on the password policy, the response either contains a part of the generated password in the field passwordFragment, or no content is returned.

Selfadmin

Required permissions

AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/password/reset
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "passwordFragment": "s2323dW"
}
Response  204
HideShow
Headers
Content-Type: application/json

FIDO REST Service

The FIDO REST Service is used to manage the FIDO UAF credentials.

FIDO UAF external IDs are unique per client only, not globally. Therefore, you must always set the target client.

Fido create DTO

The fido create DTO has the following fields:

  • extId - The external ID (string).

  • aaid - The authenticator attestation identifier (string).

  • keyId - The key identifier of the authenticator registered key (string).

  • authenticatorVersion - The version of the authenticator, as $major.$minor (string).

  • publicKey - The user authentication public key generated by the FIDO Authenticator during the registration process (string).

  • publicKeyAlgorithm - The public key algorithm used for the public key in the authenticator record (string).

  • appId - The OS-specific ID of the application that uses the FIDO credential (string).

  • deviceId - The device identifier obtained from a push service (string).

  • stateName - The state of the credential (string).

Fido DTO

The fido DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • aaid - The authenticator attestation identifier (string).

  • keyId - The key identifier of the authenticator registered key (string).

  • signCounter - Indicates how many times this authenticator has performed signatures in the past.

  • authenticatorVersion - The version of the authenticator, as $major.$minor (string).

  • appId - The OS-specific ID of the application that uses the FIDO credential (string).

  • deviceId - The device identifier obtained from a push service (string).

  • type - The type of the credential (string).

  • publicKey - The user authentication public key generated by the FIDO Authenticator during the registration process (string).

  • publicKeyAlgorithm - The public key algorithm used for the public key in the authenticator record (string).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the credential (string).

  • stateChangeDetail - Reason detail for the last state change of the credential (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (number).

  • lastFailedLoginDate - Date of last non-technical login failure (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Fido patch DTO

The fido patch DTO has the following fields:

  • signCounter - Indicates how many times this authenticator has performed signatures in the past.

  • appId - The OS-specific ID of the application that uses the FIDO credential (string).

  • deviceId - The device identifier obtained from a push service (string).

  • stateName - The state of the credential (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

FIDO UAF Credentials

Create FIDO UAF
POST/{clientExtId}/users/{userExtId}/fido-authenticators

Creates a FIDO UAF credential for the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialCreate, AccessControl.CredentialChangeState (if the state of the credential is provided, through the parameter stateName), AccessControl.CredentialView

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "fidoTestExtId",
  "aaid": "46cb#de12",
  "keyId": "Abhe2b3AHb_Ahb3hdabjHA-b5",
  "authenticatorVersion": 2,
  "publicKey": "key",
  "publicKeyAlgorithm": "algorithm",
  "appId": "abc",
  "deviceId": "deviceId",
  "stateName": "active"
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "fidoTestExtId",
  "userExtId": "1234",
  "aaid": "46cb#de12",
  "keyId": "Abhe2b3AHb_Ahb3hdabjHA-b5",
  "signCounter": 0,
  "authenticatorVersion": 2,
  "appId": "abc",
  "deviceId": "deviceId",
  "type": "FIDO UAF Authenticator",
  "publicKey": "key",
  "publicKeyAlgorithm": "algorithm",
  "stateName": "active",
  "created": "2018-07-21T19:03:49Z",
  "lastModified": "2018-07-21T19:03:49Z",
  "validity": {
    "from": "2018-07-21T19:03:49Z",
    "to": "2028-07-18T19:03:49Z"
  },
  "version": 1
}

Get user FIDO UAF credentials
GET/{clientExtId}/users/{userExtId}/fido-authenticators

Returns all the FIDO UAF credentials of the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "28000001",
      "userExtId": "1234",
      "aaid": "bbbb#aaaa",
      "keyId": "keyIdx",
      "signCounter": 1,
      "authenticatorVersion": 9,
      "appId": "appIdx",
      "deviceId": "pushTokenx",
      "type": "FIDO UAF Authenticator",
      "publicKey": "{SSHA}MsVwg87xlhHa6UzlRFBzEnRcriEChDVXqpLDWXNe",
      "publicKeyAlgorithm": "keyAlgo101",
      "stateName": "initial",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "test detail",
      "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
      "successfulLoginCount": 2,
      "lastFailedLoginDate": "2004-04-04T00:00:00Z",
      "failedLoginCount": 4,
      "created": "2010-01-01T00:00:00Z",
      "lastModified": "2013-08-17T00:00:00Z",
      "validity": {
        "from": "2012-08-17T00:00:00Z",
        "to": "2030-01-01T00:00:00Z"
      },
      "version": 3
    },
    {
      "extId": "28000000",
      "userExtId": "1234",
      "aaid": "bbbb#aaac",
      "keyId": "keyIdy",
      "signCounter": 1,
      "authenticatorVersion": 8,
      "appId": "appIdy",
      "deviceId": "pushTokeny",
      "type": "FIDO UAF Authenticator",
      "publicKey": "{SSHA}MsVwg87xlhHa6UzlRFBzEnRcriEChDVXqpLDWXNe",
      "publicKeyAlgorithm": "keyAlgo102",
      "stateName": "initial",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "test detail",
      "lastSuccessfulLoginDate": "2013-11-11T00:00:00Z",
      "successfulLoginCount": 2,
      "lastFailedLoginDate": "2004-04-04T00:00:00Z",
      "failedLoginCount": 4,
      "created": "2010-01-01T00:00:00Z",
      "lastModified": "2013-08-17T00:00:00Z",
      "validity": {
        "from": "2013-08-17T00:00:00Z",
        "to": "2030-01-01T00:00:00Z"
      },
      "version": 3
    }
  ],
  "_pagination": {
    "continuationToken": "1376697600_28000000",
    "limit": 1000
  }
}

FIDO UAF Credentials

Get FIDO UAF
GET/{clientExtId}/users/{userExtId}/fido-authenticators/{extId}

Returns the FIDO UAF credential with the given external ID, belonging to the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators/28000002
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000002

ExtID of the credential.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "28000002",
  "userExtId": "1234",
  "aaid": "46cb#de12",
  "keyId": "Abhe2b3AHb_Ahb3hdabjHA-b5",
  "signCounter": 0,
  "authenticatorVersion": 4,
  "appId": "abc",
  "deviceId": "deviceId",
  "type": "FIDO UAF Authenticator",
  "publicKey": "key",
  "publicKeyAlgorithm": "algorithm",
  "stateName": "active",
  "created": "2018-07-21T19:03:49Z",
  "lastModified": "2018-07-21T19:03:49Z",
  "validity": {
    "from": "2018-07-21T19:03:49Z",
    "to": "2028-07-18T19:03:49Z"
  },
  "version": 1
}

Delete FIDO UAF
DELETE/{clientExtId}/users/{userExtId}/fido-authenticators/{extId}

Deletes the FIDO UAF credential with the given external ID, belonging to the user with the given external ID.

since 2.73
Selfadmin

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators/28000002
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000002

ExtID of the credential.

Response  204
HideShow
Headers
Content-Type: application/json

Update FIDO UAF
PATCH/{clientExtId}/users/{userExtId}/fido-authenticators/{extId}

Updates the FIDO UAF credential with the given external ID, belonging to the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialView, AccessControl.CredentialModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators/28000002
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000002

ExtID of the credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "signCounter": 0,
  "appId": "abc",
  "deviceId": "deviceId",
  "stateName": "active",
  "modificationComment": "changed-by-admin",
  "version": 2
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "28000002",
  "userExtId": "1234",
  "aaid": "46cb#de12",
  "keyId": "Abhe2b3AHb_Ahb3hdabjHA-b5",
  "signCounter": 0,
  "authenticatorVersion": 4,
  "appId": "abc",
  "deviceId": "deviceId",
  "type": "FIDO UAF Authenticator",
  "publicKey": "key",
  "publicKeyAlgorithm": "algorithm",
  "stateName": "active",
  "created": "2018-07-21T19:03:49Z",
  "modificationComment": "changed-by-admin",
  "lastModified": "2018-07-21T19:03:49Z",
  "validity": {
    "from": "2018-07-21T19:03:49Z",
    "to": "2028-07-18T19:03:49Z"
  },
  "version": 2
}

Certificate REST Service

The Certificate REST Service is used to manage certificates. Note that changing and deleting a user’s certificate can result in the loss of access to the system for the user.

Certificate create DTO

The certificate create DTO has the following fields:

  • extId - The external ID of the certificate credential (string).

  • policyExtId - The external ID of the used policy (string).

  • stateName - The state of the credential (string).

  • certificate - The certificate value of the credential (string).

Certificate DTO

The certificate DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • policyExtId - The external ID of the used policy (string).

  • subjectDN - DN of the subject (string).

  • issuerDN - DN of the issuer (string).

  • fingerprint - Fingerprint of the certificate in hexbyte-colon notation (string).

  • serial - Serial number (string).

  • subjectKeyIdentifier - The subject key identifier extension stored in the certificate credential (string).

  • certificate - The certificate value of the credential (string).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the credential (string).

  • stateChangeDetail - Reason detail for the last state change of the credential (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (number).

  • lastFailedLoginDate - Date of last non-technical login failure (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Certificate patch DTO

The certificate patch DTO has the following fields:

  • certificate - The certificate value of the credential (string).

  • stateName - The state of the credential (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

Certificates

Create certificate
POST/{clientExtId}/users/{userExtId}/certificates

Creates a new certificate credential for the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialCreate, AccessControl.PolicyConfigurationView, AccessControl.CredentialChangeState (if the state of the credential is provided, through the parameter stateName)

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
 "extId": "4254",
 "policyExtId": "104,
 "stateName": "active",
 "certificate": "-----BEGIN CERTIFICATE-----MIICVDCCAb2gAwIBAgIBADANBgkqhkiG9w0BAQ0FADBHMQswCQYDVQQGEwJ1czERMA8GA1UECAwITmV3IFlvcmsxFzAVBgNVBAoMDlNvZnR3YXJlIEhvdXNlMQwwCgYDVQQDDANTb0gwHhcNMTgwODAyMTI1NTM2WhcNMTkwODAyMTI1NTM2WjBHMQswCQYDVQQGEwJ1czERMA8GA1UECAwITmV3IFlvcmsxFzAVBgNVBAoMDlNvZnRYXJlIEhvdXNlMQwwCgYDVQQDDANTb0gwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKZYYKWCfmKWkCtJAH25+gHclMuOMMzeBUaRBqj1ITb4XavejTslb9uGwmOV/SiBbR95kvndQdV/lip9vzakySetoFHbisuWkMEvJZnxf/xU9ldouacRbeWDkGkewMH916Gb0nbKtMo1wLo4oUl0dRsDy6vwVHa7w5xWNgrTOfDRAgMBAAGjUDBOMB0GA1UdDgQWBSwQ/cEKTYRaTvcSU3wKabc+5j5ozAfBgNVHSMEGDAWgBSwQ/cEKTYRaTvcSU3wKabc+5j5ozAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBDQUAA4GBAJqEMCovjWQ5GTHgduLkunFEValHeUYf9gV4+Ka9sUvB195XzQ0UOV/W57aMhiXoLM/2BfH7CENhEFegKW8ETEiYem1s3BvwpmJTdh3EFFM9bsLWbhTvIAtf+FhkqRXEvR56WYGwekvC6/vjICwyP7JRQnIubtKjGr2nfv/Yr39M-----END CERTIFICATE-----"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/certificates/4254

Get all certificates
GET/{clientExtId}/users/{userExtId}/certificates

Returns all certificate credentials of the user with the given external ID.

since 2.73
Selfadmin

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "created": "2018-08-07T00:00:00Z",
      "lastModified": "2018-08-07T00:00:00Z",
      "version": 1,
      "extId": "39250002",
      "userExtId": "1234",
      "policyExtId": "100",
      "subjectDN": "CN=www.getCertificateSUBJECT_DN.com",
      "issuerDN": "CN=www.getCertificateISSUER_DN.com",
      "fingerprint": "42:2D:4D:16:47:C5:FC:46:8F:1D:97:3E:DB:8B:4B:60:56:F1:D7:A7",
      "serial": "12944643904094573006",
      "subjectKeyIdentifier": "1178e0b26a1f4df8c706c51437157cce56f80316",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIID5TCCAs2g...aLpcd+Q=\n-----END CERTIFICATE-----",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "changed to disabled",
      "lastSuccessfulLoginDate": "2018-11-11T00:00:00Z",
      "successfulLoginCount": 4,
      "lastFailedLoginDate": "2018-09-04T00:00:00Z",
      "failedLoginCount": 2,
      "modificationComment": "Add certificate1",
      "validity": {
        "from": "2018-08-07T00:00:00Z",
        "to": "2052-06-03T00:00:00Z"
      },
      "type": "CERTIFICATE"
    },
    {
      "created": "2018-08-07T00:00:00Z",
      "lastModified": "2018-08-07T00:00:00Z",
      "version": 1,
      "extId": "39250001",
      "userExtId": "1234",
      "policyExtId": "100",
      "subjectDN": "EMAILADDRESS=rest@test.com, C=DJ, ST=_EMPTY_, OU=IT, O=Adnovum, CN=test.com",
      "fingerprint": "D8:45:47:EC:B6:DE:57:7E:53:E8:96:42:EC:7D:E2:63:56:82:61:70",
      "serial": "12575078455078482608",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIDejCCAmI...U+vgySk7bDMQQmBjN\n-----END CERTIFICATE-----",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "changed to disabled",
      "lastSuccessfulLoginDate": "2018-12-11T00:00:00Z",
      "successfulLoginCount": 5,
      "lastFailedLoginDate": "2018-10-06T00:00:00Z",
      "failedLoginCount": 2,
      "modificationComment": "Add certificate2",
      "validity": {
        "from": "2018-08-07T00:00:00Z",
        "to": "2052-06-03T00:00:00Z"
      },
      "type": "CERTIFICATE"
    }
  ],
  "_pagination": {
    "continuationToken": "1533600000_39250001",
    "limit": 1000
  }
}

Certificate

Get certificate
GET/{clientExtId}/users/{userExtId}/certificates/{extId}

Returns the certificate credential with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000033

ExtID of the certificate credential.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "created": "2018-08-07T00:00:00Z",
  "lastModified": "2018-08-07T00:00:00Z",
  "version": 1,
  "extId": "28000033",
  "userExtId": "1234",
  "policyExtId": "100",
  "subjectDN": "CN=www.getCertificateSUBJECT_DN.com",
  "issuerDN": "CN=www.getCertificateISSUER_DN.com",
  "fingerprint": "42:2D:4D:16:47:C5:FC:46:8F:1D:97:3E:DB:8B:4B:60:56:F1:D7:A7",
  "serial": "12944643904094573006",
  "subjectKeyIdentifier": "1178e0b26a1f4df8c706c51437157cce56f80316",
  "type": "CERTIFICATE",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIID5TCCA....8aLpcd+Q=\n-----END CERTIFICATE-----",
  "stateName": "active",
  "stateChangeReason": "changed-by-admin",
  "stateChangeDetail": "changed to disabled",
  "lastSuccessfulLoginDate": "2018-09-09T00:00:00Z",
  "successfulLoginCount": 2,
  "lastFailedLoginDate": "2018-10-12T00:00:00Z",
  "failedLoginCount": 4,
  "modificationComment": "Add certificate",
  "validity": {
    "from": "2018-08-07T00:00:00Z",
    "to": "2052-06-03T00:00:00Z"
  }
}

Update certificate
PATCH/{clientExtId}/users/{userExtId}/certificates/{extId}

Updates the certificate credential with the given external ID, belonging to the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialModify, AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000033

ExtID of the certificate credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "certificate": "-----BEGIN CERTIFICATE-----MIICVDCCAb2gAwIBAgIBADANBgkqhkiG9w0BAQ0FADBHMQswCQYDVQQGEwJ1czERMA8GA1UECAwITmV3IFlvcmsxFzAVBgNVBAoMDlNvZnR3YXJlIEhvdXNlMQwwCgYDVQQDDANTb0gwHhcNMTgwODAyMTI1NTM2WhcNMTkwODAyMTI1NTM2WjBHMQswCQYDVQQGEwJ1czERMA8GA1UECAwITmV3IFlvcmsxFzAVBgNVBAoMDlNvZnRYXJlIEhvdXNlMQwwCgYDVQQDDANTb0gwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKZYYKWCfmKWkCtJAH25+gHclMuOMMzeBUaRBqj1ITb4XavejTslb9uGwmOV/SiBbR95kvndQdV/lip9vzakySetoFHbisuWkMEvJZnxf/xU9ldouacRbeWDkGkewMH916Gb0nbKtMo1wLo4oUl0dRsDy6vwVHa7w5xWNgrTOfDRAgMBAAGjUDBOMB0GA1UdDgQWBSwQ/cEKTYRaTvcSU3wKabc+5j5ozAfBgNVHSMEGDAWgBSwQ/cEKTYRaTvcSU3wKabc+5j5ozAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBDQUAA4GBAJqEMCovjWQ5GTHgduLkunFEValHeUYf9gV4+Ka9sUvB195XzQ0UOV/W57aMhiXoLM/2BfH7CENhEFegKW8ETEiYem1s3BvwpmJTdh3EFFM9bsLWbhTvIAtf+FhkqRXEvR56WYGwekvC6/vjICwyP7JRQnIubtKjGr2nfv/Yr39M-----END CERTIFICATE-----",
  "stateName": "active",
  "modificationComment": "changed-by-admin",
  "version": 5
}
Response  200
HideShow
Body
{
  "created": "2018-08-07T00:00:00Z",
  "lastModified": "2018-08-07T00:00:00Z",
  "version": 5,
  "extId": "39250002",
  "userExtId": "1234",
  "policyExtId": "100",
  "subjectDN": "CN=www.getCertificateSUBJECT_DN.com",
  "issuerDN": "CN=www.getCertificateISSUER_DN.com",
  "fingerprint": "42:2D:4D:16:47:C5:FC:46:8F:1D:97:3E:DB:8B:4B:60:56:F1:D7:A7",
  "serial": "12944643904094573006",
  "subjectKeyIdentifier": "1178e0b26a1f4df8c706c51437157cce56f80316",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIID5TCCAs2g...aLpcd+Q=\n-----END CERTIFICATE-----",
  "stateName": "active",
  "stateChangeReason": "changed-by-admin",
  "stateChangeDetail": "changed to disabled",
  "lastSuccessfulLoginDate": "2018-11-11T00:00:00Z",
  "successfulLoginCount": 4,
  "lastFailedLoginDate": "2018-09-04T00:00:00Z",
  "failedLoginCount": 2,
  "modificationComment": "changed-by-admin",
  "validity": {
    "from": "2018-08-07T00:00:00Z",
    "to": "2052-06-03T00:00:00Z"
  },
  "type": "CERTIFICATE"
}

Delete certificate
DELETE/{clientExtId}/users/{userExtId}/certificates/{extId}

Deletes the certificate credential with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000033

ExtID of the certificate credential.

Response  204
HideShow
Headers
Content-Type: application/json

Certificate properties

Get properties
GET/{clientExtId}/users/{userExtId}/certificates/{extId}/properties/

Returns all properties of the certificate credential with the given external ID, as an object of key-value pairs. Properties are additional, customer-specific attributes of an entity.

since 2.73

Required permissions

AccessControl.CredentialView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000033

ExtID of the certificate credential.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyValue1",
  "propertyKey2": "propertyValue2"
}

Update certificate properties
PATCH/{clientExtId}/users/{userExtId}/certificates/{extId}/properties/

Updates the properties of the certificate with the given external ID, belonging to the user and client with given external IDs. The body must contain an object of key-value property pairs.

since 2.73

Required permissions

AccessControl.CredentialView, AccessControl.CredentialModify, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView, AccessControl.PropertyValueCreate, AccessControl.PropertyValueModify, AccessControl.PropertyValueDelete

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000033

ExtID of the certificate credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey2": "propertyValue2",
  "propertyKey3": "propertyNewValue3"
}

OATH REST Service

The OATH REST Service is used to manage OATH credentials. Note that deleting a user’s OATH credential can result in the loss of access to the system for the user.

OATH DTO

The OATH DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • policyExtId - The external ID of the used policy (string).

  • uri - The generated QR code in an uri format (string).

  • issuer - The issuer indicates the provider or service the OATH credential is associated with (string).

  • authenticationMethod - The authentication method to use (string).

  • hashingAlgorithm - The hashing algorithm to use (string).

  • digits - The length of the generated token (string).

  • period - The time window (in seconds) how long a TOTP token is valid (number).

  • counter - The counter for tokens. This is increased on each succesful authentication (number).

  • type - The type of the credential (string).

  • secret - The secret that is required to initialize the mobile application (string).

  • label - The label is a technical property which can be used to select an OATH credential (string).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the credential (string).

  • stateChangeDetail - Reason detail for the last state change of the credential (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (number).

  • lastFailedLoginDate - Date of last non-technical login failure, e.g., wrong password (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

OATH create DTO

The OATH create DTO has the following fields:

  • extId - The external ID of the credential (string).

  • policyExtId - The external ID of the used policy (string).

  • label - The label of the OATH credential (string).

  • stateName - The state of the credential (string).

OATH credentials

Get all OATH credentials of a user
GET/{clientExtId}/users/{userExtId}/oath-credentials/

Returns all OATH credentials of the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/oath-credentials/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "4321",
      "userExtID": "1234",
      "policyExtId": "6789",
      "issuer": "nevisIDM",
      "authenticationMethod": "TOTP",
      "hashingAlgorithm": "SHA1",
      "digits": "6",
      "period": 30,
      "type": "OATH",
      "label": "label",
      "stateName": "active",
      "stateChangeReason": "initialized",
      "stateChangeDetail": "changed-by-admin",
      "lastSuccessfulLoginDate": "2018-12-17T08:02:00Z",
      "successfulLoginCount": 2,
      "lastFailedLoginDate": "2017-10-02T08:15:00Z",
      "failedLoginCount": 1,
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2018-04-21T10:26:00Z",
      "modificationComment": "comment",
      "validity": {
        "from": "2017-08-17T00:00:00Z",
        "to": "2027-08-17T00:00:00Z"
      },
      "version": 2
    }
  ],
  "_pagination": {
    "continuationToken": "1524579740_4321",
    "limit": 100
  }
}

Create an OATH credential
POST/{clientExtId}/users/{userExtId}/oath-credentials/

Creates a new OATH credential for the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialCreate, AccessControl.CredentialView, AccessControl.PolicyConfigurationView

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/oath-credentials/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "4500",
  "policyExtId": "6789",
  "label": "label",
  "stateName": "initial"
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "4500",
  "userExtId": "1234",
  "policyExtId": "6789",
  "uri": "otpauth://totp/nevisIDM:userToCreateOrDeleteOath%40test.hu?secret=AIOT7KMBL7GCF5C7HM4X4WOWFZ2HCVJR&issuer=nevisIDM&algorithm=SHA1&digits=6&period=30",
  "issuer": "nevisIDM",
  "authenticationMethod": "TOTP",
  "hashingAlgorithm": "SHA1",
  "digits": "6",
  "period": 30,
  "counter": 0,
  "type": "OATH",
  "secret": "3/PzpeVIMuN7tUolwvpJoyZbUzhSlx0VhfBqJg8V12/3nJ7/JGUZLtU7cQXcfalp",
  "label": "label",
  "stateName": "initial",
  "stateChangeReason": "initialized",
  "created": "2018-10-15T16:02:03Z",
  "lastModified": "2018-10-15T16:02:03Z",
  "validity": {
    "from": "2018-10-15T16:02:03Z",
    "to": "2028-10-12T16:02:03Z"
  },
  "version": 1
}

OATH credential

Get the OATH credential
GET/{clientExtId}/users/{userExtId}/oath-credentials/{extId}

Returns the OATH credential with the given external ID, belonging to the user with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/oath-credentials/4321
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 4321

ExtID of the OATH credential.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "4321",
  "userExtID": "1234",
  "policyExtId": "6789",
  "issuer": "nevisIDM",
  "authenticationMethod": "TOTP",
  "hashingAlgorithm": "SHA1",
  "digits": "6",
  "period": 30,
  "type": "OATH",
  "label": "label",
  "stateName": "active",
  "stateChangeReason": "initialized",
  "stateChangeDetail": "changed-by-admin",
  "lastSuccessfulLoginDate": "2018-12-17T08:02:00Z",
  "successfulLoginCount": 2,
  "lastFailedLoginDate": "2017-10-02T08:15:00Z",
  "failedLoginCount": 1,
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2018-04-21T10:26:00Z",
  "modificationComment": "comment",
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2027-08-17T00:00:00Z"
  },
  "version": 3
}

Delete OATH credential
DELETE/{clientExtId}/users/{userExtId}/oath-credentials/{extId}

Deletes the OATH credential with the given external ID.

since 2.71
Selfadmin

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/oath-credentials/4321
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 4321

ExtID of the OATH credential.

Response  204
HideShow
Headers
Content-Type: application/json

Context Password REST Service

Context Password DTO

The Context Password DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • policyExtId - The external ID of the used policy (string).

  • resetCount - Number of times the credential was reset (number).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the credential (string).

  • stateChangeDetail - Reason detail for the last state change of the credential (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (password reset feature or administrator) (number).

  • lastFailedLoginDate - Date of last non-technical login failure, e.g., wrong password (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (password reset feature or administrator) (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • context - The value of the context field of context password credential (string).

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

  • createdBy - The combination of the client name and login ID of the user who created the context password (read-only string, not available in self admin).

  • modifiedBy - The combination of the client name and login ID of the user who last modified the context password (read-only string, not available in self admin).

  • lastChangeDate - Date when the context password was modified last time (read-only string, not available in self admin).

Context Password create DTO

The Context Password DTO has the following fields:

  • extId - The external ID of the credential (string).

  • policyExtId - The external ID of the used policy (string).

  • stateName - The state of the credential (string).

  • password - The value of the context password credential. This field is never returned (string).

  • context - The value of the context field of context password credential (string).

Context Password patch DTO

The context password patch DTO has the following fields:

  • stateName - The state of the credential (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

Context Password fragment DTO

The password fragment DTO represents the portion of the generated password that is returned to the caller. It has one field:

  • passwordFragment - A part of the generated password (string).

Context Password change DTO

The password change DTO has the following fields:

  • oldPassword - The old password. This field must be omitted when the caller changes the password of someone else (string).

  • newPassword - The new password to be set (string).

Context Passwords

Create context password
POST/{clientExtId}/users/{userExtId}/context-passwords

Creates a context password for the given user. When resetCodeEnabled is set to false in the given context password policy, or resetCodeLen0 is set to 0 then 201 is returned. Else 201 with the passwordFragment.

since 2.73

Required permissions

AccessControl.CredentialCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/27000029/context-passwords
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 27000029

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
 "extId": "1001",
 "policyExtId": "201",
 "stateName": "active",
 "password": "secretpassword",
 "context" "context"
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "passwordFragment": "A31S@ass"
}

Get all context passwords
GET/{clientExtId}/users/{userExtId}/context-passwords

Returns all context password credentials of the user with the given external ID.

since 2.73
Selfadmin

Required permissions

AccessControl.CredentialView

Technical fields limitation

Fields createdBy and modifiedBy hold the login id of the user when he created/modified the context password. This login id might differ from the current login id of the user.

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/context-passwords
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
   "items": [
    {
    "created": "2018-08-07T00:00:00Z",
    "lastModified": "2018-08-08T00:00:00Z",
    "version": 3,
    "extId": "28000046",
    "userExtId": "1234",
    "policyExtId": "127",
    "resetCount": 3,
    "stateName": "active",
    "stateChangeReason": "changed-by-admin",
    "stateChangeDetail": "testStateChangeDetail",
    "lastSuccessfulLoginDate": "2018-12-11T08:15:00Z",
    "successfulLoginCount": 3,
    "lastFailedLoginDate": "2018-11-30T08:20:00Z",
    "failedLoginCount": 3,
    "modificationComment": "testModComment3",
    "context": "restGetTestContext3",
    "validity": {
     "from": "2018-08-07T00:00:00Z",
     "to": "2052-06-03T00:00:00Z"
    },
    "type": "CONTEXTPASSWORD",
    "createdBy": "loginId",
    "modifiedBy": "loginId",
    "lastChangeDate": "2017-08-17T00:00:00Z"
    },
    {
    "created": "2018-08-07T00:00:00Z",
    "lastModified": "2018-08-08T00:00:00Z",
    "version": 2,
    "extId": "28000045",
    "userExtId": "1234",
    "policyExtId": "127",
    "resetCount": 2,
    "stateName": "active",
    "stateChangeReason": "changed-by-admin",
    "stateChangeDetail": "testStateChangeDetail",
    "lastSuccessfulLoginDate": "2018-12-11T08:15:00Z",
    "successfulLoginCount": 2,
    "lastFailedLoginDate": "2018-11-30T08:20:00Z",
    "failedLoginCount": 2,
    "modificationComment": "testModComment2",
    "context": "restGetTestContext2",
    "validity": {
     "from": "2018-08-07T00:00:00Z",
     "to": "2052-06-03T00:00:00Z"
    },
    "type": "CONTEXTPASSWORD",
    "createdBy": "loginId",
    "modifiedBy": "loginId",
    "lastChangeDate": "2017-08-17T00:00:00Z"
    },
    {
    "created": "2018-08-07T00:00:00Z",
    "lastModified": "2018-08-08T00:00:00Z",
    "version": 3,
    "extId": "28000044",
    "userExtId": "1234",
    "policyExtId": "127",
    "resetCount": 1,
    "stateName": "active",
    "stateChangeReason": "changed-by-admin",
    "stateChangeDetail": "testStateChangeDetail",
    "lastSuccessfulLoginDate": "2018-12-11T08:15:00Z",
    "successfulLoginCount":1,
    "lastFailedLoginDate": "2018-11-30T08:20:00Z",
    "failedLoginCount": 1,
    "modificationComment": "testModComment1",
    "context": "restGetTestContext1",
    "validity": {
     "from": "2018-08-07T00:00:00Z",
     "to": "2052-06-03T00:00:00Z"
    },
    "type": "CONTEXTPASSWORD",
    "createdBy": "loginId",
    "modifiedBy": "loginId",
    "lastChangeDate": "2017-08-17T00:00:00Z"
    },
   ],
   "_pagination": {
    "continuationToken": "1533600000_39250001",
    "limit": 1000
   }
  }

Context Password

Get context password
GET/{clientExtId}/users/{userExtId}/context-passwords/{extId}

Gets the context password credential with the given external ID, belonging to the user with the given external ID.

since 2.73
Selfadmin

Required permissions

AccessControl.CredentialView

Technical fields limitation

Fields createdBy and modifiedBy hold the login id of the user when he created/modified the context password. This login id might differ from the current login id of the user.

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/context-passwords/27000029
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 27000029

ExtID of the context password credential.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "created": "2018-08-07T00:00:00Z",
  "lastModified": "2018-08-08T00:00:00Z",
  "version": 2,
  "extId": "27000029",
  "userExtId": "1234",
  "policyExtId": "127",
  "resetCount": 3,
  "stateName": "active",
  "stateChangeReason": "changed-by-admin",
  "stateChangeDetail": "testStateChangeDetail",
  "lastSuccessfulLoginDate": "2018-12-11T08:15:00Z",
  "successfulLoginCount": 4,
  "lastFailedLoginDate": "2018-11-30T08:20:00Z",
  "failedLoginCount": 2,
  "modificationComment": "testModComment",
  "context": "restGetTestContext",
  "validity": {
    "from": "2018-08-07T00:00:00Z",
    "to": "2052-06-03T00:00:00Z"
  },
  "type": "CONTEXTPASSWORD",
  "createdBy": "loginId",
  "modifiedBy": "loginId",
  "lastChangeDate": "2017-08-17T00:00:00Z"
}

Delete Context Password
DELETE/{clientExtId}/users/{userExtId}/context-passwords/{extId}

Deletes the context password credential of the user with the given external ID.

since 2.73

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/context-passwords/27000029
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 27000029

ExtID of the context password credential.

Response  204
HideShow
Headers
Content-Type: application/json

Update context password
PATCH/{clientExtId}/users/{userExtId}/context-passwords/{extId}

Updates a context password for the given user. 204 (No content) is returned.

since 2.73

Required permissions

AccessControl.CredentialView AccessControl.CredentialModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/27000029/context-passwords/27000030
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 27000029

ExtID of the user.

extId
string (required) Example: 27000030

ExtID of the credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "stateName": "active",
  "modificationComment": "no comment",
  "version": 2
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "created": "2018-08-07T00:00:00Z",
  "lastModified": "2018-08-08T00:00:00Z",
  "version": 2,
  "extId": "28000046",
  "userExtId": "1234",
  "policyExtId": "127",
  "resetCount": 3,
  "stateName": "active",
  "stateChangeReason": "changed-by-admin",
  "stateChangeDetail": "testStateChangeDetail",
  "lastSuccessfulLoginDate": "2018-12-11T08:15:00Z",
  "successfulLoginCount": 3,
  "lastFailedLoginDate": "2018-11-30T08:20:00Z",
  "failedLoginCount": 3,
  "modificationComment": "no comment",
  "context": "restGetTestContext3",
  "validity": {
    "from": "2018-08-07T00:00:00Z",
    "to": "2052-06-03T00:00:00Z"
  },
  "type": "CONTEXTPASSWORD",
  "createdBy": "loginId",
  "modifiedBy": "loginId",
  "lastChangeDate": "2017-08-17T00:00:00Z"
}

Context Password Reset experimental

Reset Context Password
POST/{clientExtId}/users/{userExtId}/context-passwords/{extId}/reset

Resets the context password of the user with the given external ID. Depending on the password policy, the response either contains a part of the generated password in the field passwordFragment or no content is returned.

Selfadmin

Required permissions

AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/context-passwords/27000030/reset
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 27000030

ExtID of the credential.

Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "passwordFragment": "s2323dW"
}
Response  204
HideShow
Headers
Content-Type: application/json

Context Password Change

Change Context Password
POST/{clientExtId}/users/{userExtId}/context-passwords/{extId}/change

Changes the context password of the user with the given external ID. The oldPassword field in the request body is mandatory if a caller wants to change his own password. In case the caller wants to change the password of another user, the oldPassword field in the request body must be omitted.

since 2.73
Selfadmin

Required permissions

AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/context-passwords/5678/change
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 5678

ExtID of the context password credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "oldPassword": "oldPassword",
  "newPassword": "newSecretPassword"
}
Response  204
HideShow
Headers
Content-Type: application/json

Personal Question REST Service experimental

Personal Question DTO

The personal question DTO has the following fields:

  • extId - The external ID of the personal question (string).

  • clientExtId - The external ID of the client to which the personal question belongs (string).

  • version - Version used for optimistic locking (number).

  • description - The textual description of the personal question (string).

  • stateName - The state of the credential (string).

  • displayName - Language-dependent name of the personal question (object).

    • EN - Personal question name in English (string).
    • DE - Personal question name in German (string).
    • FR - Personal question name in French (string).
    • IT - Personal question name in Italian (string).

  • content - Language-dependent content of the personal question (object).

    • EN - Content in English (string).
    • DE - Content in German (string).
    • FR - Content in French (string).
    • IT - Content in Italian (string)

Personal Question Patch DTO

The personal question patch DTO has the following fields:

  • version - Version used for optimistic locking (number).

  • description - The textual description of the personal question (string).

  • stateName - The state of the credential (string).

  • displayName - Language-dependent name of the personal question (object).

    • EN - Personal question name in English (string).
    • DE - Personal question name in German (string).
    • FR - Personal question name in French (string).
    • IT - Personal question name in Italian (string).

  • content - Language-dependent content of the personal question (object).

    • EN - Content in English (string).
    • DE - Content in German (string).
    • FR - Content in French (string).
    • IT - Content in Italian (string)

Client personal questions

Get a personal question
GET/{clientExtId}/personal-questions/{extId}

Returns the personal question with the given external ID, belonging to the client with the given external ID.

Required permissions

AccessControl.PersonalQuestionView, AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/personal-questions/2233
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 2233

ExtID of the personal question.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2233",
  "clientExtId": "1000",
  "version": 1,
  "description": "description",
  "stateName": "active",
  "displayName": {
    "DE": "DE displayName",
    "EN": "EN displayName",
    "FR": "FR displayName",
    "IT": "IT displayName"
  },
  "content": {
    "DE": "DE content",
    "EN": "EN content",
    "FR": "FR content",
    "IT": "IT content"
  }
}

Delete a personal question
DELETE/{clientExtId}/personal-questions/{extId}

Deletes a personal question with the given external ID, belonging to the client with the given external ID.

Required permissions

AccessControl.PersonalQuestionDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/personal-questions/2233
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 2233

ExtID of the personal question.

Response  204
HideShow
Headers
Content-Type: application/json

Update a personal question
PATCH/{clientExtId}/personal-questions/{extId}

Updates the personal question with the given external ID, belonging to the client with the given external ID.

Required permissions

AccessControl.PersonalQuestionView, AccessControl.PersonalQuestionModify, AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/personal-questions/2233
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

extId
string (required) Example: 2233

ExtID of the personal question.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "version": 1,
  "description": "description",
  "stateName": "active",
  "displayName": {
    "DE": "DE displayName",
    "EN": "EN displayName",
    "FR": "FR displayName",
    "IT": "IT displayName"
  },
  "content": {
    "DE": "DE content",
    "EN": "EN content",
    "FR": "FR content",
    "IT": "IT content"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "2233",
  "clientExtId": "1000",
  "version": 1,
  "description": "description",
  "stateName": "active",
  "displayName": {
    "DE": "DE displayName",
    "EN": "EN displayName",
    "FR": "FR displayName",
    "IT": "IT displayName"
  },
  "content": {
    "DE": "DE content",
    "EN": "EN content",
    "FR": "FR content",
    "IT": "IT content"
  }
}

Generic Credential REST Service

The Generic Credential REST Service is used to manage generic credentials. Note that deleting a user’s generic credential can result in the loss of access to the system for the user.

Generic Credential DTO

The generic credential DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • policyExtId - The external ID of the used policy (string).

  • type - The type of the credential (string).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the credential (string).

  • stateChangeDetail - Reason detail for the last state change of the credential (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (number).

  • lastFailedLoginDate - Date of last non-technical login failure, e.g., wrong password (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Generic credential create DTO

The generic credential create DTO has the following fields:

  • extId - The external ID of the credential (string).

  • policyExtId - The external ID of the used policy (string).

  • identification - The identification of the generic credential (string).

  • stateName - The state of the credential (string).

Generic credential

Get Generic Credential
GET/{clientExtId}/users/{userExtId}/generic-credentials/{extId}

Returns the generic credential with the given external ID, belonging to the user with the given external ID.

since 2.73
Selfadmin

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/generic-credentials/1234
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the generic credential.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "4321",
  "userExtID": "1234",
  "policyExtId": "6789",
  "identification": "someIdentification",
  "label": "label",
  "stateName": "active",
  "stateChangeReason": "initialized",
  "stateChangeDetail": "changed-by-admin",
  "lastSuccessfulLoginDate": "2018-12-17T08:02:00Z",
  "successfulLoginCount": 2,
  "lastFailedLoginDate": "2017-10-02T08:15:00Z",
  "failedLoginCount": 1,
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2018-04-21T10:26:00Z",
  "modificationComment": "comment",
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2027-08-17T00:00:00Z"
  },
  "version": 3
}

Update a generic credential
PATCH/{clientExtId}/users/{userExtId}/generic-credentials/{extId}

Updates a generic credential with the given external ID for the user with the given external ID

since 2.73

Required permissions

AccessControl.CredentialModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/generic-credentials/1234
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the generic credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
      "policyExtId": "6789",
    "stateName": "initial",
    "identification": "identification",
    "modificationComment": "changed",
    "version": 4, 
  }
Response  200
HideShow
Body
{
  "extId": "4321",
  "userExtID": "1234",
  "policyExtId": "6789",
  "identification": "identification",
  "label": "label",
  "stateName": "active",
  "stateChangeReason": "initialized",
  "stateChangeDetail": "changed-by-admin",
  "lastSuccessfulLoginDate": "2018-12-17T08:02:00Z",
  "successfulLoginCount": 2,
  "lastFailedLoginDate": "2017-10-02T08:15:00Z",
  "failedLoginCount": 1,
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2018-04-21T10:26:00Z",
  "modificationComment": "changed",
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2027-08-17T00:00:00Z"
  },
  "version": 4
}

Delete Generic Credential
DELETE/{clientExtId}/users/{userExtId}/generic-credentials/{extId}

Deletes the generic credential of the user with the given external ID.

since 2.73

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/generic-credentials/1234
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the generic credential.

Response  204
HideShow
Headers
Content-Type: application/json

Generic credentials

Get all generic credentials
GET/{clientExtId}/users/{userExtId}/generic-credentials/

Returns all generic credentials of the user with the given external ID.

since 2.73
Selfadmin

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/250002047/generic-credentials/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 250002047

ExtID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "extId": "27000044",
      "userExtId": "250002047",
      "policyExtId": "24000037",
      "identification": "someIdentification",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "test detail",
      "lastSuccessfulLoginDate": "2002-01-01T00:00:00Z",
      "lastFailedLoginDate": "2002-01-01T00:00:00Z",
      "successfulLoginCount": 1,
      "failedLoginCount": 1,
      "created": "2001-01-01T00:00:00Z",
      "lastModified": "2002-01-01T00:00:00Z",
      "modificationComment": "comment",
      "validity": {
        "from": "2001-01-01T00:00:00Z",
        "to": "2029-01-01T00:00:00Z"
      },
      "version": 0
    },
    {
      "extId": "27000043",
      "userExtId": "250002047",
      "policyExtId": "24000037",
      "identification": "someIdentification",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "test detail",
      "lastSuccessfulLoginDate": "2002-01-01T00:00:00Z",
      "lastFailedLoginDate": "2002-01-01T00:00:00Z",
      "successfulLoginCount": 1,
      "failedLoginCount": 1,
      "created": "2001-01-01T00:00:00Z",
      "lastModified": "2002-01-01T00:00:00Z",
      "modificationComment": "comment",
      "validity": {
        "from": "2001-01-01T00:00:00Z",
        "to": "2029-01-01T00:00:00Z"
      },
      "version": 0
    },
    {
      "extId": "27000040",
      "userExtId": "250002047",
      "policyExtId": "24000037",
      "identification": "someIdentification",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "test detail",
      "lastSuccessfulLoginDate": "2002-01-01T00:00:00Z",
      "lastFailedLoginDate": "2002-01-01T00:00:00Z",
      "successfulLoginCount": 1,
      "failedLoginCount": 0,
      "created": "2001-01-01T00:00:00Z",
      "lastModified": "2002-01-01T00:00:00Z",
      "modificationComment": "comment",
      "validity": {
        "from": "2001-01-01T00:00:00Z",
        "to": "2029-01-01T00:00:00Z"
      },
      "version": 0
    }
  ],
  "_pagination": {
    "continuationToken": "978303600000_27000040",
    "limit": 1000
  }
}

Create a generic credential
POST/{clientExtId}/users/{userExtId}/generic-credentials/

Creates a new generic credential for the user with the given external ID.

since 2.73

Required permissions

AccessControl.CredentialCreate, AccessControl.CredentialView, AccessControl.PolicyConfigurationView

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/250002047/generic-credentials/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 250002047

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "4500",
  "policyExtId": "6789",
  "identification": "someIdentification",
  "stateName": "active"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/users/1001/generic-credentials/4500

Generic credential properties

Get properties
GET/{clientExtId}/users/{userExtId}/generic-credentials/{extId}/properties/

Returns all properties of the generic credential with the given external ID, as an object of key-value pairs. Properties are additional, customer-specific attributes of an entity.

since 2.73

Required permissions

AccessControl.CredentialView, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/generic-credentials/28000033/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000033

ExtID of the generic credential.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyValue1",
  "propertyKey2": "propertyValue2"
}

Update generic credential properties
PATCH/{clientExtId}/users/{userExtId}/generic-credentials/{extId}/properties/

Updates the properties of the generic credential with the given external ID, belonging to the user and client with given external IDs. The body must contain an object of key-value property pairs.

since 2.73

Required permissions

AccessControl.CredentialView, AccessControl.CredentialModify, AccessControl.PropertyView, AccessControl.PropertyValueView, AccessControl.PropertyAllowedValueView, AccessControl.PropertyValueCreate, AccessControl.PropertyValueModify, AccessControl.PropertyValueDelete

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/generic-credentials/28000033/properties/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 28000033

ExtID of the generic credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "propertyKey1": "propertyNewValue1",
  "propertyKey2": "propertyValue2",
  "propertyKey3": "propertyNewValue3"
}

Terms REST Service

These endpoints enable the caller

  • to create and delete terms,

  • to change the existing terms.

  • to (un)/assign an application (from)/to a terms.

A terms object can be associated with many applications.

Terms get DTO

The terms get DTO has the following fields:

  • extId - The external id of the Terms object (string).

  • name - The name of the Terms object (string).

  • active - Determines whether the terms are active or not (boolean).

  • silentAcceptance - Determines whether the terms are accepted silently or not (boolean).

  • termsVersion - The version of the Terms (string).

  • created - The creation date (Date).

  • lastModified - The date of the last modification (Date).

  • urls - Actual Terms and Conditions pages (string: string pairs).

  • applicationExtIds - List of external ids of the applications for which the terms are assigned.

Terms create DTO

The terms create DTO has the following fields:

  • extId - The external id of the Terms object (string).

  • name - The name of the Terms object (string).

  • active - Determines whether the terms are active or not (boolean).

  • silentAcceptance - Determines whether the terms are accepted silently or not (boolean).

  • termsVersion - The version of the Terms (string).

  • urls - Actual Terms and Conditions pages (string).

Terms patch DTO

The terms patch DTO has the following fields:

  • name - The name of the Terms (string).

  • active - Determines whether the terms are active or not (boolean).

  • termsVersion - The version of the Terms (string).

  • version - The version used for optimistic locking (number).

  • urls - Actual Terms and Conditions pages (string).

Terms

Create terms
POST/terms/

Creates a new terms object with the given external ID and name.

since 2.75.1

Required permissions

AccessControl.TermsCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/terms/
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1001",
  "name": "termsName",
  "silentAcceptance": true,
  "active": true,
  "termsVersion": "termsVersion",
  "urls": {
    "de": "https://www.sampleUrl.terms",
    "fr": "https://www.sampleUrl2.terms"
  }
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/terms/1001

Get terms
GET/terms/

Returns a list of all terms objects in the system.

since 2.75.1

Required permissions

AccessControl.TermsView

Example URI

GET https://your-host/nevisidm/api/core/v1/terms/
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    Items: [
        {
            "extId": "1001",
            "name": "termsOne",
            "silentAcceptance": true,
            "active": true,
            "created": "2018-04-24T14:22:20Z",
            "lastModified": "2018-04-24T14:22:20Z"
            "termsVersion": "version",
            "version": 1,
            "urls": {
                "de": "https://www.sampleUrl.terms"
            },
            "applicationExtIds": [
                "10101",
                "20202"
            ]
        },
        {
            "extId": "1002",
            "name": "termsTwo",
            "silentAcceptance": true,
            "active": true,
            "created": "2018-04-24T16:22:20Z",
            "lastModified": "2018-04-24T16:22:20Z"
            "termsVersion": "version",
            "version": 1,
            "urls": {
                "de": "https://www.sampleUrl.terms",
                "fr": "https://www.sampleUrl2.terms"
            },
            "applicationExtIds": [
                "11111",
                "22222"
            ]
        }
    ]
}

Terms

Get terms
GET/terms/{extId}

Returns the terms with the given external ID.

since 2.75.1

Required permissions

AccessControl.TermsView

Example URI

GET https://your-host/nevisidm/api/core/v1/terms/250000003
URI Parameters
HideShow
extId
string (required) Example: 250000003

ExtID of the terms.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "1001",
  "name": "termsName",
  "silentAcceptance": true,
  "active": true,
  "termsVersion": "termsVersion",
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2017-08-17T00:00:00Z",
  "urls": {
    "de": "https://www.sampleUrl.terms",
    "it": "https://www.sampleUrl2.terms"
  },
  "applicationExtIds": [
    "10101",
    "20202"
  ]
}

Update terms
PATCH/terms/{extId}

Updates the terms with the given external ID.

since 2.75.1

Required permissions

AccessControl.TermsView, AccessControl.TermsModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/terms/250000003
URI Parameters
HideShow
extId
string (required) Example: 250000003

ExtID of the terms.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "termsName",
  "silentAcceptance": true,
  "active": true,
  "termsVersion": "termsVersion",
  "version": 1,
  "urls": {
    "de": "https://www.sampleUrl.terms",
    "fr": "https://www.sampleUrl2.terms"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "extId": "1001",
    "name": "termsName",
    "silentAcceptance": true,
    "active": true,
    "created": "2018-04-24T14:22:20Z",
    "lastModified": "2018-04-24T14:22:20Z"
    "termsVersion": "termsVersion",
    "version": 1,
    "urls": {
        "es": "https://www.sampleUrl.terms",
        "it": "https://www.sampleUrl2.terms"
    },
    "applicationExtIds": [
        "11111",
        "22222",
    ]
}

Delete terms
DELETE/terms/{extId}

Deletes the terms with the given external ID.

since 2.75.1

Required permissions

AccessControl.TermsDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/terms/250000003
URI Parameters
HideShow
extId
string (required) Example: 250000003

ExtID of the terms.

Response  204
HideShow
Headers
Content-Type: application/json

Terms

Assigns an application to a terms
PUT/terms/{termsExtId}/applications/{applicationExtId}

Assigns an application with the given external ID to the terms with the given external ID.

since 2.75.1

Required permissions

AccessControl.TermsModify

Example URI

PUT https://your-host/nevisidm/api/core/v1/terms/250000003/applications/26000001
URI Parameters
HideShow
termsExtId
string (required) Example: 250000003

ExtID of the terms.

applicationExtId
string (required) Example: 26000001

ExtId of the application.

Response  204
HideShow
Headers
Content-Type: application/json

Unassign an application from a terms
DELETE/terms/{termsExtId}/applications/{applicationExtId}

Unassigns an application with the given external ID from the terms with the given external ID.

since 2.75.1

Required permissions

AccessControl.TermsView, AccessControl.TermsModify

Example URI

DELETE https://your-host/nevisidm/api/core/v1/terms/250000003/applications/26000001
URI Parameters
HideShow
termsExtId
string (required) Example: 250000003

ExtID of the terms.

applicationExtId
string (required) Example: 26000001

ExtId of the application.

Response  204
HideShow
Headers
Content-Type: application/json

Kerberos REST Service experimental

The Kerberos REST Service is used to manage the Kerberos credentials.

Kerberos external IDs are unique per client only, not globally. Therefore, you must always set the target client.

Kerberos create DTO

The Kerberos create DTO has the following fields:

  • extId - The external ID of the Kerberos credential (string).

  • stateName - The state of the credential (string).

  • kerberosId - The identifier of the Kerberos credential (string).

Kerberos get DTO

The kerberos credential get DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • kerberosId - The external ID used to map the user to the SAM account (string).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the credential (string).

  • stateChangeDetail - Reason detail for the last state change of the credential (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (number).

  • lastFailedLoginDate - Date of last non-technical login failure (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Kerberos patch DTO

The kerberos credential patch DTO has the following fields:

  • kerberosId - The external ID used to map the user to the SAM account (string).

  • stateName - The state of the credential (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

Kerberos Credentials

Create Kerberos
POST/{clientExtId}/users/{userExtId}/kerberos/

Creates a Kerberos credential for the user with the given external ID.

Required permissions

AccessControl.CredentialCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "kerberosExtId",
  "kerberosId": "someKerberosId",
  "stateName": "active"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/users/1001/kerberos/kerberosExtId

Get all Kerberos Credentials
GET/{clientExtId}/users/{userExtId}/kerberos/

Returns all Kerberos credentials of the user with the given user external ID.

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "created": "2018-08-07T00:00:00Z",
      "lastModified": "2018-08-07T00:00:00Z",
      "version": 0,
      "extId": "250002053",
      "userExtId": "250002052",
      "kerberosId": "user-login-ID-1@windows-domain",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "changed to disabled",
      "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
      "successfulLoginCount": 2,
      "lastFailedLoginDate": "2004-04-04T00:00:00Z",
      "failedLoginCount": 4,
      "modificationComment": "Add kerberos credential 1",
      "validity": {
        "from": "2018-08-07T00:00:00Z",
        "to": "2052-06-03T00:00:00Z"
      }
    },
    {
      "created": "2018-08-07T00:00:00Z",
      "lastModified": "2018-08-07T00:00:00Z",
      "version": 0,
      "extId": "250002052",
      "userExtId": "250002052",
      "kerberosId": "user-login-ID-2@windows-domain",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "changed to disabled",
      "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
      "successfulLoginCount": 2,
      "lastFailedLoginDate": "2004-04-04T00:00:00Z",
      "failedLoginCount": 4,
      "modificationComment": "Add kerberos credential 2",
      "validity": {
        "from": "2018-08-07T00:00:00Z",
        "to": "2052-06-03T00:00:00Z"
      }
    }
  ],
  "_pagination": {
    "start": 0,
    "limit": 1000
  }
}

Kerberos credential

Get Kerberos Credential
GET/{clientExtId}/users/{userExtId}/kerberos/{extId}/

Returns the Kerberos credential with the given external ID, belonging to the user with the given external ID.

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/1234/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the Kerberos credential.

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "created": "2018-08-07T00:00:00Z",
  "lastModified": "2018-08-07T00:00:00Z",
  "version": 0,
  "extId": "250002053",
  "userExtId": "250002052",
  "kerberosId": "user-login-ID-1@windows-domain",
  "stateName": "active",
  "stateChangeReason": "changed-by-admin",
  "stateChangeDetail": "changed to disabled",
  "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
  "successfulLoginCount": 2,
  "lastFailedLoginDate": "2004-04-04T00:00:00Z",
  "failedLoginCount": 4,
  "modificationComment": "Add kerberos credential 1",
  "validity": {
    "from": "2018-08-07T00:00:00Z",
    "to": "2052-06-03T00:00:00Z"
  }
}

Delete Kerberos credential
DELETE/{clientExtId}/users/{userExtId}/kerberos/{extId}/

Deletes the Kerberos credential of the user with the given external ID.

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/1234/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the Kerberos credential.

Response  204
HideShow
Headers
Content-Type: application/json

Update Kerberos credential
PATCH/{clientExtId}/users/{userExtId}/kerberos/{extId}/

Updates the Kerberos credential with the given external ID, belonging to the user with the given external ID.

Required permissions

AccessControl.CredentialModify, AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/1234/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the Kerberos credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "kerberosId": "user-login-ID-1@windows-domain",
  "stateName": "active",
  "modificationComment": "Update kerberos comment",
  "version": 4
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "created": "2018-08-07T00:00:00Z",
  "lastModified": "2018-08-07T00:00:00Z",
  "version": 4,
  "extId": "250002053",
  "userExtId": "250002052",
  "kerberosId": "user-login-ID-1@windows-domain",
  "stateName": "active",
  "stateChangeReason": "changed-by-admin",
  "stateChangeDetail": "changed to disabled",
  "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
  "successfulLoginCount": 2,
  "lastFailedLoginDate": "2004-04-04T00:00:00Z",
  "failedLoginCount": 4,
  "modificationComment": "Update kerberos comment",
  "validity": {
    "from": "2018-08-07T00:00:00Z",
    "to": "2052-06-03T00:00:00Z"
  }
}

mTAN REST Service

The mTAN REST Service is used to manage the mTAN credentials.

mTAN external IDs are unique per client only, not globally. Therefore, you must always set the target client.

mTAN create DTO

The mTAN create DTO has the following fields:

  • extId - The external ID of the mTan credential (string).

  • mobileNumber - The mobile number in E164 format to associate with the mTan credential (string).

  • policyExtId - The external ID of the used policy (string).

mTAN get DTO

The mTAN credential get DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • policyExtId - The external ID of the used policy (string).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the credential (string).

  • stateChangeDetail - Reason detail for the last state change of the credential (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (number).

  • lastFailedLoginDate - Date of last non-technical login failure (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • mobileNumber - Mobile number of the mTAN credential

    • raw - Mobile number in raw format
    • e164 - Mobile number in E.164 format, omitted if raw cannot be parsed

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

mTAN patch DTO

The mTAN credential patch DTO has the following fields:

  • stateName - The state of the credential (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

mTAN Credentials

Create mTAN
POST/{clientExtId}/users/{userExtId}/mtans/

Creates an mTAN credential for the user with the given external ID.

since 2.74

Required permissions

AccessControl.CredentialCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/mtans/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "mTanExtId",
  "mobileNumber": "+41442726111",
  "policyExtId": "6789"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/users/1001/mtans/mTanExtId

Get all mTAN Credentials
GET/{clientExtId}/users/{userExtId}/mtans/

Returns all mTAN credentials of the user with the given user external ID.

since 2.74

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/mtans/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "items": [
        {
            "created": "2018-08-07T00:00:00Z",
            "lastModified": "2018-08-07T00:00:00Z",
            "version": 0,
            "extId": "250002053",
            "userExtId": "250002052",
            "stateName": "active",
            "stateChangeReason": "changed-by-admin",
            "stateChangeDetail": "changed to disabled",
            "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
            "successfulLoginCount": 2,
            "lastFailedLoginDate": "2004-04-04T00:00:00Z",
            "failedLoginCount": 4,
            "modificationComment": "Add mTAN credential 1",
            "mobileNumber": {
                "raw": "36201111111",
                "e164": "+36201111111"
            }
            "validity": {
                "from": "2018-08-07T00:00:00Z",
                "to": "2052-06-03T00:00:00Z"
            }
        },
        {
            "created": "2018-08-07T00:00:00Z",
            "lastModified": "2018-08-07T00:00:00Z",
            "version": 0,
            "extId": "250002052",
            "userExtId": "250002052",
            "stateName": "active",
            "stateChangeReason": "changed-by-admin",
            "stateChangeDetail": "changed to disabled",
            "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
            "successfulLoginCount": 2,
            "lastFailedLoginDate": "2004-04-04T00:00:00Z",
            "failedLoginCount": 4,
            "modificationComment": "Add mTAN credential 2",
            "mobileNumber": {
                "raw": "36201111111",
                "e164": "+36201111111"
            }
            "validity": {
                "from": "2018-08-07T00:00:00Z",
                "to": "2052-06-03T00:00:00Z"
            }
        }
    ],
    "_pagination": {
        "start": 0,
        "limit": 1000
    }
}

mTAN credential

Get mTAN Credential
GET/{clientExtId}/users/{userExtId}/mtans/{extId}/

Returns the mTAN credential with the given external ID, belonging to the user with the given external ID.

since 2.74

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/mtans/1234/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the mTAN credential.

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2017-08-17T00:00:00Z",
  "version": 0,
  "extId": "232334",
  "userExtID": "123234",
  "policyExtId": "100",
  "stateName": "active",
  "stateChangeReason": "hanged-by-admin",
  "stateChangeDetail": "changed to disabled",
  "lastSuccessfulLoginDate": "2017-08-17T00:00:00Z",
  "successfulLoginCount": 0,
  "lastFailedLoginDate": "2017-08-17T00:00:00Z",
  "failedLoginCount": 0,
  "modificationComment": "comment",
  "mobileNumber": {
    "raw": "36201111111",
    "e164": "+36201111111"
  },
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2017-08-17T00:00:00Z"
  }
}

Update mTAN Credential
PATCH/{clientExtId}/users/{userExtId}/mtans/{extId}/

Updates the mTAN credential with the given external ID, belonging to the user with the given external ID.

since 2.74

Required permissions

AccessControl.CredentialModify, AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/mtans/1234/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the mTAN credential.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "stateName": "active",
  "modificationComment": "Update mTAN comment",
  "version": 4
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2017-08-17T00:00:00Z",
  "version": 4,
  "extId": "232334",
  "userExtID": "123234",
  "policyExtId": "100",
  "stateName": "active",
  "stateChangeReason": "hanged-by-admin",
  "stateChangeDetail": "changed to active",
  "lastSuccessfulLoginDate": "2017-08-17T00:00:00Z",
  "successfulLoginCount": 0,
  "lastFailedLoginDate": "2017-08-17T00:00:00Z",
  "failedLoginCount": 0,
  "modificationComment": "Update mTAN comment",
  "mobileNumber": {
    "raw": "36201111111",
    "e164": "+36201111111"
  },
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2017-08-17T00:00:00Z"
  }
}

Delete mTan Credential
DELETE/{clientExtId}/users/{userExtId}/mtans/{extId}/

Deletes the mTan credential with the given external ID, belonging to the user with the given user external ID.

since 2.74

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/mtans/1234/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

extId
string (required) Example: 1234

ExtID of the mTAN credential.

Response  204
HideShow
Headers
Content-Type: application/json

SecurID REST Service

The SecurID REST Service is used to manage the SecurID credentials.

SecurID external IDs are unique per client only, not globally. Therefore, you must always set the target client.

SecurID create DTO

The SecurID create DTO has the following fields:

  • extId - The external ID of the SecurID credential (string).

  • username - The SecurID user name (string).

  • stateName - The state of the credential (string).

SecurID get DTO

The SecurID get DTO has the following fields:

  • created - Creation time of the SecurID (read-only string).

  • lastModified - Last modification time of the SecurID (read-only string).

  • version - Version used for optimistic locking (number).

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user (string).

  • stateName - The state of the credential (string).

  • username - The SecurID username (string).

  • stateChangeReason - The reason for the last change (string).

  • stateChangeDetail - The details of the last change (string).

  • lastSuccessfulLoginDate - The time of the last successful login (read-only string).

  • successfulLoginCount - the count of the successful login attempts (number).

  • lastFailedLoginDate - the time of the last failed login (read-only string).

  • failedLoginCount - The count of the failed login attempts (number).

  • modificationComment - The comment provided for the modification (string).

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

SecurID Credential

Create SecurID
POST/{clientExtId}/users/{userExtId}/securid/

Creates a SecurID credential for the user with the given external ID.

since 2.75.1

Required permissions

AccessControl.CredentialCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/securid/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "securIdExtId",
  "username": "securid_username",
  "stateName": "active"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/users/1001/securids/securIdExtId

Get SecurID Credential
GET/{clientExtId}/users/{userExtId}/securid/

Returns the SecurID credential belonging to the user with the given external ID.

since 2.75.1

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/securid/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
      "created": "2018-08-07T00:00:00Z",
      "lastModified": "2018-08-07T00:00:00Z",
      "version": 0,
      "extId": "39250002",
      "userExtId": "2345",
      "stateName": "active",
      "username": "securid_username",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "changed to disabled",
      "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
      "successfulLoginCount": 2,
      "lastFailedLoginDate": "2004-04-04T00:00:00Z",
      "failedLoginCount": 4,
      "modificationComment": "Add",
      "validity": {
        "from": "2018-08-07T00:00:00Z",
        "to": "2052-06-03T00:00:00Z"
      }    
}

Delete SecurID Credential experimental
DELETE/{clientExtId}/users/{userExtId}/securid/

Deletes the SecurID credential associated to the user with the given external ID.

Required permissions

AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/securid/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  204
HideShow
Headers
Content-Type: application/json

Safeword REST Service experimental

The Safeword REST Service is used to manage the Safeword credentials.

Safeword external IDs are unique per client only, not globally. Therefore, you must always set the target client.

Safeword create DTO

The Safeword create DTO has the following fields:

  • extId - The external ID of the Safeword credential (string).

  • stateName - The state of the credential (string).

  • username - The username of the Safeword credential (string).

Safeword get DTO

The safeword credential get DTO has the following fields:

  • extId - The external ID of the credential (string).

  • userExtId - The external ID of the user to whom the credential belongs(string).

  • username - The content of the safeword credential (string).

  • stateName - The state of the credential (string).

  • stateChangeReason - Reason for the last state change of the credential (string).

  • stateChangeDetail - Reason detail for the last state change of the credential (string).

  • lastSuccessfulLoginDate - Timestamp of last successful login (string).

  • successfulLoginCount - Counts successful logins with this credential since last initialization or reset (number).

  • lastFailedLoginDate - Date of last non-technical login failure (string).

  • failedLoginCount - Counts non-technical login failures since the last successful login, initialization or reset (number).

  • modificationComment - Textual comment regarding the last modification (string).

  • validity - Describes the validity period of the credential (object).

    • from - Start date of the profile’s validity in ISO format (string).
    • to - End date of the profile’s validity in ISO format (string).

  • version - Version used for optimistic locking (number).

  • created - Creation date of the entity (read-only string).

  • lastModified - Date when the entity was last modified (read-only string).

Safeword patch DTO

The Safeword patch DTO has the following fields.

  • username - The username of the Safeword credential (string).

  • stateName - The state of the credential (string).

  • modificationComment - Textual comment regarding the last modification (string).

  • version - Version used for optimistic locking (number).

Safeword Credential

Create Safeword
POST/{clientExtId}/users/{userExtId}/safeword/

Creates a Safeword credential for the user with the given external ID.

Required permissions

AccessControl.CredentialCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/safeword/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "safewordExtId",
  "username": "username",
  "stateName": "active"
}
Response  201
HideShow
Headers
Location: https://your-host/nevisidm/api/core/v1/1000/users/1001/safewords/safewordExtId

Delete safeword credential
DELETE/{clientExtId}/users/{userExtId}/safeword/

Deletes the safeword credential of the user specified with the userExtId

Required permissions

AccessControl.CredentialModify, AccessControl.CredentialView

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/safeword/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Response  204
HideShow
Headers
Content-Type: application/json

Getting a Safeword credential
GET/{clientExtId}/users/{userExtId}/safeword/

Returns the Safeword credential with the given external ID, belonging to the user with the given external ID.

Required permissions

AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/safeword/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "4321",
  "userExtId": "1234",
  "username": "safeword username",
  "stateName": "active",
  "stateChangeReason": "initialized",
  "stateChangeDetail": "changed-by-admin",
  "lastSuccessfulLoginDate": "2018-12-17T08:02:00Z",
  "successfulLoginCount": 2,
  "lastFailedLoginDate": "2017-10-02T08:15:00Z",
  "failedLoginCount": 1,
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2018-04-21T10:26:00Z",
  "modificationComment": "comment",
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2027-08-17T00:00:00Z"
  },
  "version": 3
}

Update Safeword Credential
PATCH/{clientExtId}/users/{userExtId}/safeword/

Updates the Safeword credential with the given external ID, belonging to the user with the given external ID.

Required permissions

AccessControl.CredentialModify, AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/safeword/
URI Parameters
HideShow
clientExtId
string (required) Example: 1000

ExtID of the client.

userExtId
string (required) Example: 1234

ExtID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "safeword-patch-01",
  "stateName": "active",
  "modificationComment": "safeword-patch-01 comment",
  "version": 5
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "extId": "4321",
  "userExtId": "1234",
  "username": "safeword username",
  "stateName": "active",
  "stateChangeReason": "initialized",
  "stateChangeDetail": "changed-by-admin",
  "lastSuccessfulLoginDate": "2018-12-17T08:02:00Z",
  "successfulLoginCount": 2,
  "lastFailedLoginDate": "2017-10-02T08:15:00Z",
  "failedLoginCount": 1,
  "created": "2017-08-17T00:00:00Z",
  "lastModified": "2018-04-21T10:26:00Z",
  "modificationComment": "comment",
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2027-08-17T00:00:00Z"
  },
  "version": 3
}

Generated by aglio on 11 Feb 2020