nevisIDM Core REST API

Introduction

The nevisIDM Core REST API enables to query and manipulate the managed identity objects in nevisIDM using 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 parameters that contain additional, Customer-specific information about an object.

Managed identity objects

The identity objects of nevisIDM look 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 parameter 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 checks whether the version of the object being modified is up to date. If it is, the modification is stored, if it is not, an error message is 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]"
                    }]
        }

Note that if the version number is not included in the request body, the object is 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 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, for example: https://your-host/nevisidm/api/core/v1/clients?limit=3&continuationToken=1536444000000_1002

Filtering of result lists

When performing a GET request to retrieve a list of results, the result set can be filtered using request query parameters. (Support for filtering by custom properties is only available for users yet.) All endpoints which support filtering are marked with the tag:

Filter

If nothing else is indicated, all attributes of the returned DTO are supported as query parameters. Nested attributes can be used composing the attributes with a ‘.’.

Example of filtering

When sending a GET request to the URL https://your-host/nevisidm/api/core/v1/clients/100/users?userState=active&address.countryCode=ch, all active users in Switzerland are returned.

• Response 200 (application/json)

  • Body

    {
            "items": [
                {
                    "created": "2020-10-07T08:14:23Z",
                    "lastModified": "2020-10-07T08:14:23Z",
                    "version": 0,
                    "extId": "1000",
                    "clientExtId": "100",
                    "userState": "active",
                    "loginId": "userA",
                    "languageCode": "de",
                    "isTechnicalUser": false,
                    "name": {
                        "title": "Ms.",
                        "firstName": "User",
                        "familyName": "A"
                    },
                    "sex": "female",
                    "gender": "female",
                    "birthDate": "1984-05-08",
                    "address": {
                        "postalCode": "8000",
                        "city": "Zurich",
                        "street": "Bahnhofstrasse",
                        "houseNumber": "100",
                        "countryCode": "ch"
                    },
                    "contacts": {
                        "telephone": "0444444444",
                        "mobile": "0794444444",
                        "email": "[email protected]"
                    }
                },
                {
                    "created": "2020-10-07T08:14:23Z",
                    "lastModified": "2020-10-07T08:14:23Z",
                    "version": 0,
                    "extId": "1001",
                    "clientExtId": "100",
                    "userState": "active",
                    "loginId": "userB",
                    "languageCode": "en",
                    "isTechnicalUser": false,
                    "name": {
                        "title": "Mr.",
                        "firstName": "User",
                        "familyName": "B"
                    },
                    "sex": "male",
                    "gender": "male",
                    "birthDate": "1984-05-08",
                    "address": {
                        "postalCode": "8000",
                        "city": "Zurich",
                        "street": "Poststrasse",
                        "houseNumber": "200",
                        "countryCode": "ch"
                    },
                    "contacts": {
                        "telephone": "0445555555",
                        "mobile": "0765555555",
                        "email": "[email protected]"
                    }
                }
            ],
            "_pagination": {
                "continuationToken": "1602051280000_1001",
                "limit": 1000
            },
            "_classifications": {
                "personal": [
                    "name.firstName",
                    "name.familyName",
                    "contacts.mobile"
                ],
                "gov": [
                    "address"
                ]
            }
        }

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 to classify information, as 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 parameters occurs in line with the syntax data.classifications.<level>.<object>.

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

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

The validation of parameters 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 parameters are enforced, too. Hence, the following scenarios are 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 returned in this format only 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.

Self-admin

Calls that can be used for self-administration are marked with the self-admin tag. Calls for self-administration sent by a user to view or modify his own data only require the permission AccessControl.self-admin. 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.

Mandatory

Value for the parameters of POST requests that are marked as MANDATORY has to be specified by the client.

Optional

The parameter is optional on the interface. All the parameters of PATCH requests are optional.

Filter

Calls that support filtering.

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, that is, 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 is changed, or a value represents an invalid state. This error code always refers to business errors.
• 500 - A technical, non-business-related error 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 have to be logged in to nevisIDM so that you can 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 is not to fully represent the object model of the nevisIDM web application. This is because not all parameters of an object are exposed.
• When you use PATCH to update resources with the API, all “null” values are ignored. Note that for some parameters you cannot set the attributes back to “empty”.

Client REST Service

Clients are representing “virtual organizations” or tentants. In some cases, our customers want to handle different organizations separately. Consider, for example, the customer McDanold, a fake fast food restaurant. This customer is present in different markets: EMEA, ASPAC, and AMERICAS. The organizations in the different markets have to fulfill 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 (for example, 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 get DTO

The client get DTO has the following parameters:

• 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 (string).
• lastModified - Date when the entity was last modified (string).

User get DTO

The user get DTO has the following parameters:

• 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 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 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).
  • locality - The locality of the user address (string).
• contacts - Telephone numbers and email addresses on which the user can be contacted (object).
  • telephone - The number of the user landline (string).
  • telefax - The fax number of the user (string).
  • mobile - The cellphone number of the user (string).
  • email - the email address of the user (string).
• validity - The validity period of the user entity (object).
  • to - The end date of the user validity period in ISO format (string).
  • from - The start date of the user 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 (string).
• lastModified - Date when the entity was last modified (string).
• classifications - The defined classifications of the user (map<string, list>).
• properties - Custom properties of the user (map<string, string>).
• lastSuccessfulLoginDate - Timestamp of last successful login (string).
• lastFailedLoginDate - Date of last non-technical login failure, for example, wrong password (string).

Application get DTO

• The application get DTO has the following parameters:
• extId - External ID of the application (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 is to 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 (string).
• lastModified - Date when the entity was last modified (string).

Enterprise Role get DTO

The enterprise role get DTO has the following parameters:

• 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).

Unit get DTO

The unit get DTO has the following parameters:

• extId - The external ID of the unit (string).
• parentUnitExtId - The external ID of the parent unit (string).
• clientExtId - The external ID of the client the unit belongs to (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 (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 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 validity period in ISO format (string).
  • to - The end date of the unit 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 (string).
• lastModified - Date when the entity was last modified (string).

Count DTO

The count DTO has the following parameter:

• count - The count of the requested resources (long).

FIDO2 get DTO

The FIDO2 get DTO has the following parameters:

• extId - The external ID of the credential (string).
• userExtId - The external ID of the user to whom the credential belongs (string).
• aaguid - A 128-bit identifier indicating the type (for example, make and model) of the authenticator (string).
• authenticator - The authenticator used for FIDO2 which can contains credentialId (string).
• hashedCredentialId - The hashed value of credential ID generated by the authenticator (string).
• rpId - The domain of the party who uses this authentication for its website (string).
• authenticatorAttachment - The value of authenticator’s AuthenticatorAttachment parameter, possible values are ‘platform’ and ‘crossplatform’ (string).
• attestationConveyancePreference - The value of authenticator’s AuthenticatorAttachment parameter, possible values are ‘direct’, ‘indirect’, ‘none’ and ‘enterprise’ (string).
• residentKeyRequirement - The value of authenticator’s ResidentKey parameter, which is contains if the server is willing to store private keys, possible values are ‘required’ and ‘discouraged’ (string).
• stateName - The state of the credential (string, default:active).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• userAgent - UserAgent of the browser used (string).
• userFriendlyName - Human readable name of the credential (string).
• userVerificationRequirement - Contains the value of the authenticator User Verification parameter, which decides which process is used for verification. Possible values are: ‘required’, ‘preferred’ and ‘discouraged’ (string).
• type - The type 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 (string).
• lastModified - Date when the entity was last modified (string).

Fido UAF get DTO

The FIDO UAF get DTO has the following parameters:

• 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).
  • Available values:
    • ACTIVE,
    • DISABLED
• 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 validity in ISO format (string).
  • to - End date of the profile 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).
• policyExtId - The external ID of the used policy (string).
• dispatchTargetExtId - In contrast with the deviceId this field can guarantee a unique 1:N association between the dispatch target and the UAF credential (string).

Generic Credential get DTO

The generic credential get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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, for example, 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 validity in ISO format (string).
  • to - End date of the profile 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).
• properties - Custom properties of the credential (map<string, 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

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "extId": "1001",
      "name": "McDanold ASPAC",
      "displayName": {
        "EN": "McDanold ASPAC",
        "DE": "McDanold ASPAC",
        "FR": "McDanold ASPAC",
        "IT": "McDanold ASPAC"
      },
      "version": 2,
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    },
    {
      "extId": "1000",
      "name": "McDanold EMEA",
      "displayName": {
        "EN": "McDanold EMEA",
        "DE": "McDanold EMEA",
        "FR": "McDanold EMEA",
        "IT": "McDanold EMEA"
      },
      "version": 0,
      "created": "2017-08-17T00:00:00Z",
      "lastModified": "2017-08-17T00:00:00Z"
    }
  ],
  "_pagination": {
    "continuationToken": "1502928000000_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

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1000",
  "name": "McDanold EMEA",
  "displayName": {
    "EN": "McDanold EMEA",
    "DE": "McDanold EMEA",
    "FR": "McDanold EMEA",
    "IT": "McDanold 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.

Supports sorting result via sortBy query parameter, possible values:

Total result count is displayed in totalResult is displayed in _pagination if returnTotalResultCount is set to true in the request.

• extId,
• loginId,
• isTechnicalUser,
• name.title,
• name.firstName,
• name.familyName,
• birthDate,
• address.countryCode,
• address.city,
• address.postalCode,
• address.addressline1,
• address.addressline2,
• address.street,
• address.houseNumber,
• address.dwellingNumber,
• address.postOfficeBoxText,
• address.postOfficeBoxNumber,
• address.locality,
• contacts.telephone,
• contacts.telefax,
• contacts.mobile,
• contacts.email,
• validity.to,
• validity.from,
• remarks,
• version,
• created,
• lastModified

Support offset based pagination. The offset query parameter is used to specify the offset of the first result to be returned. If the continuation token and offset both provided, the continuation token is ignored.

since 2.71

Filter

The results can be filtered by property or by any field, the user has:

• extId
• userState
• loginId
• languageCode
• isTechnicalUser
• name.title
• name.firstName
• name.familyName
• sex
• gender
• birthDate
• address.countryCode
• address.city
• address.postalCode
• address.addressline1
• address.addressline2
• address.street
• address.houseNumber
• address.dwellingNumber
• address.postOfficeBoxText
• address.postOfficeBoxNumber
• address.locality
• contacts.telephone
• contacts.telefax
• contacts.email
• contacts.mobile
• validity.from
• validity.to
• remarks
• modificationComment
• version
• created
• lastModified

Use + or %20 in place of the space character to filter out properties with spaces in their names (RFC 1738).

Two modifier attachable to the end of the filter’s key is supported for the filtering on extId and loginId:

• _SW - filters not by full match but by the start of the value
• _IEQ - filters by case-insensitive full match.

Examples of filtering

• https://your-host/nevisidm/api/core/v1/clients/100/users?property.user%20global%20test%201=ffgg&property.user%20global%20test%20status=ACTIVE
• https://your-host/nevisidm/api/core/v1/clients/100/users?property.user+global+test+1=ffgg&property.user+global+test+status=ACTIVE
• https://your-host/nevisidm/api/core/v1/clients/100/users?extId=100&userState=ACTIVE
• https://your-host/nevisidm/api/core/v1/clients/100/users?extId_SW=boo&userState=ACTIVE
• https://your-host/nevisidm/api/core/v1/clients/100/users?extId_IEQ=BoOtStRaP&userState=ACTIVE
• https://your-host/nevisidm/api/core/v1/clients/100/users?loginId=bootstrap&languageCode=en
• https://your-host/nevisidm/api/core/v1/clients/100/users?loginId_SW=boo&languageCode=en
• https://your-host/nevisidm/api/core/v1/clients/100/users?loginId_IEQ=BOOTSTRAP&languageCode=en
• https://your-host/nevisidm/api/core/v1/clients/100/users?isTechnicalUser=false&name.title=Mr.
• https://your-host/nevisidm/api/core/v1/clients/100/users?address.addressline1=Addressline1&address.addressline1=Addressline2
• https://your-host/nevisidm/api/core/v1/clients/100/users?address.street=Roentgenstrasse&address.houseNumber=22
• https://your-host/nevisidm/api/core/v1/clients/100/users?address.dwellingNumber=10&address.postOfficeBoxText=Post%20Box%20Text
• https://your-host/nevisidm/api/core/v1/clients/100/users?contacts.telephone=0444444444&[email protected]
• https://your-host/nevisidm/api/core/v1/clients/100/users?modificationComment=Modification%20comment&lastModified=2023-11-23T10:30:14Z

Example of sorting

• https://your-host/nevisidm/api/core/v1/clients/100/users?sortBy=extId
• https://your-host/nevisidm/api/core/v1/clients/100/users?sortBy=extId_DESC
• https://your-host/nevisidm/api/core/v1/clients/100/users?sortBy=extId_ASC

Required permissions

• AccessControl.ClientView,
• AccessControl.UserView,
• AccessControl.PropertyView,
• AccessControl.PropertyValueView,
• AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/users

URI ParametersHide

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• 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": "[email protected]"
      },
      "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",
      "properties": {
        "custom_property1": "value1",
        "custom_property2": "value2"
      }
    },
    {
      "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": "[email protected]"
      },
      "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",
      "properties": {
        "custom_property1": "value1",
        "custom_property2": "value2"
      }
    }
  ],
  "_pagination": {
    "continuationToken": "1502928000000_12314abc",
    "limit": 100,
    "totalResult": 2
  }
}

Count client users

Count client users

GET /clients/{clientExtId}/users/count/

Returns the count of users in the client with the given external ID.

since 2.80

Filter

Required permissions

• AccessControl.ClientView,
• AccessControl.UserView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/users/count/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "count": 1024
}

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

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• 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": "1502928000000_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

• 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

• 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

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• 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": "1502928000000_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

Filter

The results can be filtered by:

• name
• hname
• extid
• state
• location
• description

Use + or %20 in place of the space character to filter out spaces in their names (RFC 1738).

Examples of filtering

• https://your-host/nevisidm/api/core/v1/clients/100/units?name=Default
• https://your-host/nevisidm/api/core/v1/clients/100/units?hname=/100
• https://your-host/nevisidm/api/core/v1/clients/100/units?extid=100
• https://your-host/nevisidm/api/core/v1/clients/100/units?name=Default&state=active
• https://your-host/nevisidm/api/core/v1/clients/100/units?location=Budapest
• https://your-host/nevisidm/api/core/v1/clients/100/units?description=Default+unit

Required permissions

• AccessControl.ClientView,
• AccessControl.UnitView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/units

URI Parameters

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• 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": "1502928000000_100",
    "limit": 100
  }
}

Client policies

Get client policies

GET /clients/{extId}/policies/

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

since 2.79

Required permissions

• AccessControl.ClientView,
• AccessControl.PolicyConfigurationView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/policies/

URI Parameters

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• 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"
  },
  "parameters": {
    "param1": "value1",
    "param2": "value2new",
    "paramN": "valueN"
  }
 ],
  "_pagination": {
     "continuationToken": "1524579739000_99990049",
     "limit":100
  }
}

Client FIDO2 Credentials

Get client FIDO2 credentials

GET /clients/{extId}/fido2/

Returns all FIDO2 credentials related to the client with the given extId.

Supports sorting result via sortBy query parameter, possible values:

• extId,
• validity.to,
• validity.from,
• version,
• created,
• lastModified,
• aaguid,
• rpId,
• userFriendlyName

Support offset based pagination. The offset query parameter is used to specify the offset of the first result to be returned. If the continuation token and offset both provided, the continuation token is ignored.

Total result count is displayed in totalResult is displayed in _pagination if returnTotalResultCount is set to true in the request.

since 2.86

Filter

The results can be filtered by:

• userFriendlyName
• extId
• hashedCredentialId
• stateName

Two modifier attachable to the end of the filter’s key is supported for the filtering on extId and userFriendlyName:

• _SW - filters not by full match but by the start of the value
• _IEQ - filters by case-insensitive full match.

Example of filtering

• https://your-host/nevisidm/api/core/v1/clients/100/fido2?userFriendlyName=NEVIS%20Android%20phone&stateName=active
• https://your-host/nevisidm/api/core/v1/clients/100/fido2?userFriendlyName_IEQ=nevis%20Android%20phone&stateName=active
• https://your-host/nevisidm/api/core/v1/clients/100/fido2?userFriendlyName_SW=NEVIS&stateName=active
• https://your-host/nevisidm/api/core/v1/clients/100/fido2?hashedCredentialId=hashedCredentialId
• https://your-host/nevisidm/api/core/v1/clients/100/fido2?extId=fido2TestExtId
• https://your-host/nevisidm/api/core/v1/clients/100/fido2?extId_SW=fido2TestExtId
• https://your-host/nevisidm/api/core/v1/clients/100/fido2?extId_IEQ=fido2TestExtId

Example of sorting

• https://your-host/nevisidm/api/core/v1/clients/100/fido2?sortBy=extId
• https://your-host/nevisidm/api/core/v1/clients/100/fido2?sortBy=extId_DESC
• https://your-host/nevisidm/api/core/v1/clients/100/fido2?sortBy=extId_ASC

Required permissions

• AccessControl.ClientView,
• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/fido2/

URI Parameters

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "created": "2021-11-26T15:25:42Z",
      "lastModified": "2021-11-26T15:25:42Z",
      "version": 0,
      "extId": "fido2user1_fido2_credential",
      "userExtId": "10000000000",
      "aaguid": "cb69481e-8ff7-4039-93ec-0a2729a154a8",
      "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a707150622e706e67",
      "authenticatorAttachment": "platform",
      "attestationConveyancePreference": "direct",
      "hashedCredentialId": "YmqcB3lo1skz629IIiYauEzEdGnxjq+XHgMYryTmgV3w6eM9+5JUcGwn2hJB0whyh9wI+ib7mg8HbshNKmE0A==",
      "rpId": "siven.ch",
      "residentKeyRequirement": "required",
      "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
      "userFriendlyName": "NEVIS Android phone",
      "userVerificationRequirement": "required",
      "stateName": "active",
      "type": "FIDO2 Authenticator",
      "validity": {
        "from": "2021-11-26T15:25:42Z",
        "to": "2031-11-24T15:25:42Z"
      }
    },
    {
      "created": "2021-11-26T15:25:42Z",
      "lastModified": "2021-11-26T15:25:42Z",
      "version": 0,
      "extId": "fido2user2_fido2_credential",
      "userExtId": "10000000001",
      "aaguid": "cb69481e-8ff7-4039-93ec-0a2729a154a8",
      "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a707150622e706e67",
      "authenticatorAttachment": "platform",
      "attestationConveyancePreference": "direct",
      "hashedCredentialId": "8Qe6LaBZ+mQOzLlTPoWaZDX2uDqi4GNqR0RN/c3jOm4fPMHJQ3vP1CZ1ryZaDQudZshsnmY0eqQVNCBHReQfuA==",
      "rpId": "siven.ch",
      "residentKeyRequirement": "required",
      "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
      "userFriendlyName": "NEVIS Android phone",
      "userVerificationRequirement": "required",
      "stateName": "active",
      "type": "FIDO2 Authenticator",
      "validity": {
        "from": "2021-11-26T15:25:42Z",
        "to": "2031-11-24T15:25:42Z"
      }
    },
    {
      "created": "2021-11-26T15:25:42Z",
      "lastModified": "2021-11-26T15:25:42Z",
      "version": 0,
      "extId": "fido2user3_fido2_credential",
      "userExtId": "10000000002",
      "aaguid": "cb69481e-8ff7-4039-93ec-0a2729a154a8",
      "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a707150622e706e67",
      "authenticatorAttachment": "platform",
      "attestationConveyancePreference": "direct",
      "hashedCredentialId": "8Qe6LaBZ+mQOzLlTPoWaZDX2uDqi4GNqR0RN/c3jOm4fPMHJQ3vP1CZ1ryZaDQudZshsnmY0eqQVNCBHReQfuA==",
      "rpId": "siven.ch",
      "residentKeyRequirement": "required",
      "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
      "userFriendlyName": "NEVIS Android phone",
      "userVerificationRequirement": "required",
      "stateName": "active",
      "type": "FIDO2 Authenticator",
      "validity": {
        "from": "2021-11-26T15:25:42Z",
        "to": "2031-11-24T15:25:42Z"
      }
    }
  ],
  "_pagination": {
    "continuationToken": "1637936742000_fido2user3_fido2_credential",
    "limit": 1000,
    "totalResult": 3
  }
}

Client Generic Credentials

Get client Generic credentials

GET /clients/{extId}/generic-credentials/

Returns all Generic Credentials related to the client with the given extId.

Total result count is displayed in totalResult is displayed in _pagination if returnTotalResultCount is set to true in the request.

Supports sorting result via sortBy query parameter, possible values:

• extId,
• validity.to,
• validity.from,
• version,
• created,
• lastModified

Support offset based pagination. The offset query parameter is used to specify the offset of the first result to be returned. If the continuation token and offset both provided, the continuation token is ignored.

since 7.2405.0

Filter

The results can be filtered by:

• extId
• property.*

Two modifier attachable to the end of the filter’s key is supported for the filtering:

• _SW - filters not by full match but by the start of the value
• _IEQ - filters by case-insensitive full match. (has to be set on the property portion of the filter)

Example of filtering

• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?extId=exampleExtId
• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?extId_IEQ=exampleExtId
• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?extId_SW=exampleExtId
• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?property.fidouaf_device_id=deviceIdNr1
• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?property_SW.fidouaf_device_id=deviceIdNr1
• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?property_IEQ.fidouaf_device_id=deviceIdNr1

Example of sorting

• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?sortBy=extId
• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?sortBy=extId_DESC
• https://your-host/nevisidm/api/core/v1/clients/100/generic-credentials?sortBy=extId_ASC

Required permissions

• AccessControl.ClientView,
• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/generic-credentials/

URI Parameters

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "created": "2010-01-01T00:00:00Z",
      "lastModified": "2010-08-17T00:00:00Z",
      "version": 3,
      "createdBy": "Default/bootstrap",
      "modifiedBy": "Default/bootstrap",
      "lastChangeDate": "2012-08-17T00:00:00Z",
      "extId": "2001",
      "userExtId": "2001",
      "policyExtId": "100",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "test detail",
      "type": "Generic Credential",
      "validity": {
        "from": "2012-08-17T00:00:00Z",
        "to": "2030-01-01T00:00:00Z"
      },
      "identification": "generic",
      "properties": {
        "fidouaf_device_id": "deviceIdNr1",
        "fidouaf_signature_key": "deviceSignatureKeyNr1",
        "fidouaf_name": "deviceNameNr1"
      }
    }
  ],
  "_pagination": {
    "continuationToken": "1262300400000_2001",
    "limit": 1000,
    "totalResult": 1
  }
}

Generic credentials

Delete Generic Credential

DELETE /clients/{clientExtId}/generic-credentials/{credentialExtId}/

Deletes the generic credential on the client with the given external ID.

since 7.2405

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/clients/1000/generic-credentials/250002047/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• credentialExtId: string (required) Example: 250002047

  ExtID of the credential.

Response 204

• Headers: Content-Type: application/json

Client FIDO UAF Credentials

Get client FIDO UAF credentials

GET /clients/{extId}/fido-uaf/

Returns all FIDO UAF credentials related to the client with the given extId.

since 7.2402.0

Filter

The results can be filtered by:

• aaid
• keyId
• appId
• deviceId
• stateName
• dispatchTargetExtId

Example of filtering

• https://your-host/nevisidm/api/core/v1/clients/100/fido-uaf?deviceId=pushTokeny&stateName=initial
• https://your-host/nevisidm/api/core/v1/clients/100/fido-uaf?keyId=keyIdy
• https://your-host/nevisidm/api/core/v1/clients/100/fido-uaf?appId=appIdx&aaid=ccaa%23aaaa

Required permissions

• AccessControl.ClientView,
• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/fido-uaf/

URI Parameters

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "created": "2010-01-01T00:00:00Z",
      "lastModified": "2010-08-17T00:00:00Z",
      "version": 3,
      "createdBy": "Default/bootstrap",
      "modifiedBy": "Default/bootstrap",
      "lastChangeDate": "2012-08-17T00:00:00Z",
      "extId": "250002999",
      "userExtId": "250002999",
      "policyExtId": "100",
      "stateName": "initial",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "test detail",
      "type": "FIDO UAF Authenticator",
      "validity": {
        "from": "2012-08-17T00:00:00Z",
        "to": "2030-01-01T00:00:00Z"
      },
      "aaid": "ccaa#aaaa",
      "keyId": "keyIdy",
      "signCounter": 1,
      "authenticatorVersion": 8,
      "appId": "appIdx",
      "deviceId": "pushTokeny",
      "publicKey": "{SSHA}MsVwg87xlhHa6UzlRFBzEnRcriEChDVXqpLDWXNe",
      "publicKeyAlgorithm": "keyAlgo101"
    },
    {
      "created": "2010-01-01T00:00:00Z",
      "lastModified": "2010-08-17T00:00:00Z",
      "version": 3,
      "createdBy": "Default/bootstrap",
      "modifiedBy": "Default/bootstrap",
      "lastChangeDate": "2012-08-17T00:00:00Z",
      "extId": "250003999",
      "userExtId": "250002999",
      "policyExtId": "100",
      "stateName": "initial",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "test detail",
      "type": "FIDO UAF Authenticator",
      "validity": {
        "from": "2012-08-17T00:00:00Z",
        "to": "2030-01-01T00:00:00Z"
      },
      "aaid": "ccaa#abba",
      "keyId": "keyIdtest",
      "signCounter": 1,
      "authenticatorVersion": 8,
      "appId": "appIdxTest",
      "deviceId": "pushTokentest",
      "publicKey": "{SSHA}MsVwg87xlhHa6UzlRFBzEnRcriEChDVXqpLDWXNe",
      "publicKeyAlgorithm": "keyAlgo101Test"
    }
  ],
  "_pagination": {
    "continuationToken": "1262300400000_250003999",
    "limit": 100
  }
}

List All properties for client

Get all the properties for a client

GET /clients/{extId}/properties/

Returns all the properties related to the client with the given extId.

since 2.85

Filter

The results can be filtered by:

• scope
• name
• encrypted

Example of filtering

• https://your-host/nevisidm/api/core/v1/clients/100/properties?scope=onUnitGlobal&name=prop-unit&encrypted=false

Required permissions

• AccessControl.PropertyView,
• AccessControl.PropertyAllowedValueView

Example URI

GET https://your-host/nevisidm/api/core/v1/clients/1000/properties/

URI Parameters

• extId: string (required) Example: 1000

  ExtID of the client.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "propertyId": 24000041,
      "name": "prop-unit",
      "description": "Unit property for testing delete property",
      "type": "String",
      "scope": "onUnitGlobal",
      "encrypted": false,
      "propagated": false,
      "stringMaxLen": 250,
      "accessCreate": "READ_WRITE",
      "accessModify": "READ_WRITE",
      "guiPrecedence": 0
    }
  ]
}

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 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 always have to 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 create DTO

The unit create DTO has the following parameters:

Mandatory

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

Optional

• extId - The external ID of the unit (read-only string).
• parentUnitExtId - The external ID of the parent unit (read-only string).
• name - The name of the unit (string, default: generated by application.generators.name.unit).
• 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 name (object).
  • EN - Abbreviation in English (string).
  • DE - Abbreviation in German (string).
  • FR - Abbreviation in French (string).
  • IT - Abbreviation in Italian (string).
• validity - The validity period of the unit entity (object).
  • from - The start date of the unit validity period in ISO format (string).
  • to - The end date of the unit validity period in ISO format (string).
• modificationComment - Textual comment regarding the last modification (string).

Unit get DTO

The unit get DTO has the following parameters:

• extId - The external ID of the unit (string).
• parentUnitExtId - The external ID of the parent unit (string).
• clientExtId - The external ID of the client the unit belongs to (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 (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 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 validity period in ISO format (string).
  • to - The end date of the unit 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 (string).
• lastModified - Date when the entity was last modified (string).

Unit patch DTO

The unit patch DTO has the following parameters:

• description - The textual description of the unit (string).
• name - The name 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 name (object).
  • EN - Abbreviation in English (string).
  • DE - Abbreviation in German (string).
  • FR - Abbreviation in French (string).
  • IT - Abbreviation in Italian (string).
• validity - The validity period of the unit entity (object).
  • from - The start date of the unit validity period in ISO format (string).
  • to - The end date of the unit validity period in ISO format (string).
• modificationComment - Textual comment regarding the last modification (string).
• version - Version used for optimistic locking (number).

Property get DTO

The property get DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Property patch DTO

The property patch DTO has the following parameter:

• values - Property name-value pairs. (map<string, 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1000",
  "parentUnitExtId": "100",
  "name": "MyUnit1",
  "location": "something",
  "description": "something",
  "displayName": {
    "EN": "MyUnit1_EN",
    "DE": "MyUnit1_DE",
    "FR": "MyUnit1_FR",
    "IT": "MyUnit1_IT"
  },
  "abbreviation": {
    "EN": "MU1_EN",
    "DE": "MU1_DE",
    "FR": "MU1_FR",
    "IT": "MU1_IT"
  },
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "profileless": false,
  "modificationComment": "blabla"
}

Response 201

• 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.

since 2.71

Required permissions

• AccessControl.UnitView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/units/1000

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the unit.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1000",
  "parentUnitExtId": "100",
  "clientExtId": "1000",
  "version": 10,
  "hierarchicalName": "100/1000",
  "name": "MyUnit1",
  "location": "something",
  "description": "something",
  "displayName": {
    "EN": "MyUnit1_EN",
    "DE": "MyUnit1_DE",
    "FR": "MyUnit1_FR",
    "IT": "MyUnit1_IT"
  },
  "abbreviation": {
    "EN": "MU1_EN",
    "DE": "MU1_DE",
    "FR": "MU1_FR",
    "IT": "MU1_IT"
  },
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "profileless": false,
  "modificationComment": "blabla",
  "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

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the unit.

Request

• Headers: Content-Type: application/json
• Body:

{
  "version": 2,
  "name": "MyUnit1New",
  "location": "somethingNew",
  "description": "somethingNew",
  "displayName": {
    "DE": "MyUnit1_DE_new",
    "EN": "MyUnit1_EN_new",
    "IT": "MyUnit1_IT_new",
    "FR": "MyUnit1_FR_new"
  },
  "abbreviation": {
    "DE": "MU1_DE_new",
    "EN": "MU1_EN_new",
    "IT": "MU1_IT_new",
    "FR": "MU1_FR_new"
  },
  "profileless": true,
  "modificationComment": "blablaNew",
  "validity": {
    "from": "2100-01-01T00:00:00Z",
    "to": "2200-01-01T00:00:00Z"
  }
}

Response 200

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

• Headers: Content-Type: application/json
• Body:

{
  "created": "2020-09-02T14:36:35Z",
  "lastModified": "2020-09-02T14:40:08Z",
  "version": 3,
  "extId": "1000",
  "parentUnitExtId": "100",
  "clientExtId": "100",
  "hierarchicalName": "/100/1000",
  "name": "MyUnit1New",
  "location": "somethingNew",
  "description": "somethingNew",
  "displayName": {
    "DE": "MyUnit1_DE_new",
    "EN": "MyUnit1_EN_new",
    "IT": "MyUnit1_IT_new",
    "FR": "MyUnit1_FR_new"
  },
  "abbreviation": {
    "DE": "MU1_DE_new",
    "EN": "MU1_EN_new",
    "IT": "MU1_IT_new",
    "FR": "MU1_FR_new"
  },
  "profileless": false,
  "modificationComment": "blablaNew",
  "validity": {
    "from": "2100-01-01T00:00:00Z",
    "to": "2200-01-01T00:00:00Z"
  }
}

Child units

Get children

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

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

since 2.79

Required permissions

• AccessControl.UnitView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/units/1000/children

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the unit.

Response 200

• 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": "1524579740000_1002",
    "limit": 100
  }
}

Child Unit

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.

since 2.79

Required permissions

• AccessControl.UnitModify

Example URI

PUT https://your-host/nevisidm/api/core/v1/1000/units/1000/children/1003

URI Parameters

• 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.

since 2.79

Required permissions

• AccessControl.UnitModify,
• AccessControl.UnitCreateTopUnit

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/units/1000/children/1003

URI Parameters

• 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

Get properties

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.

since 2.79

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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the unit.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyValue1",
  "propertyName2": "propertyValue2"
}

Update unit properties

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 has to contain an object of key-value property pairs.

since 2.79

Required permissions

• AccessControl.UnitView,
• AccessControl.UnitModify,
• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the unit.

Request

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "",
  "propertyName3": "propertyNewValue3"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyName2": "propertyValue2",
  "propertyName3": "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 always have to set the target client.

User create DTO

The user create DTO has the following parameters:

Optional

• loginId - The login ID (username) of the user. Generated by the login id generator if the value is not provided and the generator is enabled (string).
• extId - The external ID of the user. Can only be set on creation.
• userState - The state of the user (string, default:active).
• 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, mandatory if validation.user.name.mandatory policy is set).
  • familyName - The last name of the user (string, mandatory if validation.user.firstname.mandatory policy is set).
• sex - The biological sex of the user. This is not the same as legal gender (string, mandatory if validation.user.sex.mandatory policy is set).
• 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 date of birth in ISO format (string).
• address - The address of the user (object).
  • countryCode - The ISO country code of the user (string, mandatory if validation.user.country.mandatory policy is set).
  • 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 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).
  • locality - The locality of the user address (string).
• contacts - Telephone numbers and email addresses on which the user can be contacted (object).
  • telephone - The number of the user landline (string, mandatory if validation.user.phone.regex policy is set).
  • telefax - The fax number of the user (string).
  • mobile - The cellphone number of the user (string, mandatory if validation.user.mobile.mandatory policy is set).
  • email - the email address of the user (string, mandatory if validation.user.email.mandatory policy is set).
• validity - The validity period of the user entity (object).
  • to - The end date of the user validity period in ISO format (string).
  • from - The start date of the user validity period in ISO format (string).
• remarks - General textual remark about the user (string).
• properties - Custom properties of the user (map<string, string>).
• modificationComment - Textual comment on the last modification (string).

User get DTO

The user get DTO has the following parameters:

• 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 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 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).
  • locality - The locality of the user address (string).
• contacts - Telephone numbers and email addresses on which the user can be contacted (object).
  • telephone - The number of the user landline (string).
  • telefax - The fax number of the user (string).
  • mobile - The cellphone number of the user (string).
  • email - the email address of the user (string).
• validity - The validity period of the user entity (object).
  • to - The end date of the user validity period in ISO format (string).
  • from - The start date of the user 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 (string).
• lastModified - Date when the entity was last modified (string).
• classifications - The defined classifications of the user (map<string, list>).
• properties - Custom properties of the user (map<string, string>).
• lastSuccessfulLoginDate - Timestamp of last successful login (string).
• lastFailedLoginDate - Date of last non-technical login failure, for example, wrong password (string).

User patch DTO

The user patch DTO has the following parameters:

• loginId - The login ID (username) of the user (string).
• userState - The state of the user (string, default:active).
• languageCode - The default language of the user (string).
• 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 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 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).
  • locality - The locality of the user address (string).
• contacts - Telephone numbers and email addresses on which the user can be contacted (object).
  • telephone - The number of the user landline (string).
  • telefax - The fax number of the user (string).
  • mobile - The cellphone number of the user (string).
  • email - the email address of the user (string).
• validity - The validity period of the user entity (object).
  • to - The end date of the user validity period in ISO format (string).
  • from - The start date of the user 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).

Profile create DTO

The profile create DTO has the following parameters:

Optional

• extId - The external ID of the profile (read-only string).
• unitExtId - The external ID of the unit to which the profile belongs (read-only string).
• name - The name of the profile (string).
• profileState - The state of the profile (string, default:active).
• 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 validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).

Profile get DTO

The profile get DTO has the following parameters:

• extId - The external ID of the profile (string).
• userExtId - The external ID of the user to whom the profile belongs (string).
• unitExtId - The external ID of the unit to which the profile belongs (string).
• clientExtId - The external ID of the client to which the policy belongs (string).
• deputedProfileExtId - The external ID of the deputed profile (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 validity in ISO format (string).
  • to - End date of the profile 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).

Consent create DTO

The consent create DTO has the following parameters:

Mandatory

• termsExtId - External ID of the terms.

Consent get DTO

The consent get DTO has the following parameters:

• termsExtId - External ID of the term (string).
• acceptanceDate - Date when the user accepted of the term (string).
• termsVersion - Version of the term which was accepted (string).

Terms get DTO

The terms get DTO has the following parameters:

• 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.

Property get DTO

The property get DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Property get DTO with classification

The property get DTO with classification has the following parameters:

• values - Property name-value pairs. (map<string, string>).
• _classifications - The defined classifications of the property (map<string, list>).

Property patch DTO

The property patch DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Count DTO

The count DTO has the following parameter:

• count - The count of the requested resources (long).

Update Login Info DTO

The update login information DTO has the following parameters:

Mandatory

• success - Determines whether the login process was successful or not (boolean).

Optional

• credentialExtId - References to the credential, that must exist, must belong to the user, and must be active (string).

Login Status DTO

The login status DTO has the following parameters:

• statusCode - Indicates login status after processing update login information (integer).
• description - Human readable login status information (string).

Ticket GET DTO

The ticket get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • Ticket Authorization
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• ticket - Hashed ticket value with message digest algorithm prefix (string).

Otp GET DTO

The otp get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • OTP Card
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• otp - Indexed table of small passwords. The parts separated by ‘|’ sign by name: rows|cols|counters|card(|latestChallenge). (string).

TempStrongPassword GET DTO

The temporary strong password get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • Temporary Strong Password
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• tempStrongPassword - Hashed password value with message digest algorithm prefix. This password is only valid for a single login operation. Therefore, it could also be described as a one-time password credential, which is considered an exceptionally strong authentication method (string).

Vasco GET DTO

The vasco get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • Vasco
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• vascoTokens - Array of vascoDpTokens (list).
  • authMode - The authentication use case the data block is used for (string).
  • data - The Vasco Digipass data block (string).

PUK GET DTO

The PUK get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • PUK
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• puk - Hashed ticket value with message digest algorithm prefix. SSHA is alias for SHA and SSHA256 is alias for SHA-256 algorithms (string).

Device Password GET DTO

The device password get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • DevicePassword
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• devicePassword - Hashed password value with message digest algorithm prefix. SSHA is alias for SHA and SSHA256 is alias for SHA-256 algorithms (string).

Mobile Signature GET DTO

The mobile signature get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • MobileSignature
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• identificator - MSSP-specific identificator of the mobile signature credential (string).
• msspIdentifier - URI-based identifier of MSSP (string).
• signerCert - X509 signer certificate in PEM format (string).
• msisdn - Calling number for mobile device according to ETSI Standard (string).

SAML Federation GET DTO

The saml federation get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • SAML Federation
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• subjectNameId - Identifies of the subject of the SAML assertion (generally user to be authenticated) (string).
• subjectNameIdFormat - Aligns the expectations between the identity provider and the service provider on the user identity that is communicated. (string).
• issuerNameId - Identifies of the issuer of the SAML assertion (string).
• issuerNameIdFormat - Aligns the expectations between the identity provider and the service provider on the user identity that is communicated (string).
• credentialValue - Hashed identification value with optional message digest algorithm prefix. SSHA is alias for SHA-1 and SSHA256 is alias for SHA-256 algorithms (string).

Security Questions GET DTO

The security questions get DTO has the following parameters:

• created - Creation time of the credential (string).
• lastModified - Last modification time of the credential (string).
• version - Version used for optimistic locking (number).
• createdBy - The combination of the client name and login ID of the user who created the credential (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 credential (read-only string, not available in self-admin).
• lastChangeDate - Date when the credential was modified last time (read-only string, not available in self-admin).
• extId - The external ID of the credential (string).
• userExtId - The external ID of the user (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• stateChangeReason - The reason for the last change (string).
• modificationComment - The comment provided for the modification (string).
• type - The type of the credential (string).
  • Security Questions
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• personalAnswers - Array of personal answers (list).
  • personalAnswer:
    • content - Symmetrically encrypted answer of user (string).
    • revealCount - Number of times the answer has been revealed to an admin. It gets a default value of ‘0’ during credential creation (integer).
    • successCount - Number of times the answer has been verified. It gets a default value of ‘0’ during credential creation (integer).
    • failureCount - Number of times the security question was answered incorrectly. It gets a default value of ‘0’ during credential creation (integer).
    • personalQuestionExtId - External identifier of the answer’s question (string).

Users

Create user

POST /{clientExtId}/users/

Creates a new user for the client with the given external ID. From the version 2.82 creating the custom properties of a user in the same call is also possible.

since 2.71

Required permissions

• AccessControl.UserCreate,
• AccessControl.LoginIdOverride (for overriding the generated value of loginId generator, if enabled),
• AccessControl.UserCreateTechUser (for creating technical users only)

Required permissions for setting custom properties (optional)

• AccessControl.UserView,
• AccessControl.UserModify,
• AccessControl.PropertyView,
• AccessControl.PropertyValueView,
• AccessControl.PropertyAllowedValueView,
• AccessControl.PropertyValueCreate,
• AccessControl.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

Request

• 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,
    "locality": "Province XYZ"
  },
  "contacts": {
    "telephone": "+41781254153",
    "telefax": "+41781254154",
    "mobile": "+41781254156",
    "email": "[email protected]"
  },
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2022-01-01T12:00:00Z"
  },
  "remarks": "This is the new test user john doe",
  "modificationComment": "They live in ZH",
  "properties": {
    "custom_property1": "value1",
    "custom_property2": "value2"
  }
}

Response 201

• 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. Custom properties and classifications may be returned with the user, but if the caller does not have the right to access them, then they is simply omitted from the DTO.

since 2.71

Self-admin

Required permissions

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

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1000

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Response 200

• 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,
    "locality": "Province XYZ"
  },
  "contacts": {
    "telephone": "+41781254153",
    "telefax": "+41781254154",
    "mobile": "+41781254156",
    "email": "[email protected]"
  },
  "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",
  "_classifications": {
    "personal": [
      "extId",
      "userExtId",
      "unitExtId",
      "clientExtId",
      "deputedProfileExtId"
    ],
    "sensitive": [
      "validity.from",
      "validity.to",
      "remarks",
      "modificationComment"
    ]
  },
  "properties": {
    "custom_property1": "value1",
    "custom_property2": "value2"
  }
}

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

Self-admin

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

• 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. From the version 2.82 updating the custom properties of a user in the same call is also possible. (But that feature does not work in self-admin mode.)

since 2.71

Self-admin

Required permissions

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

Required permissions for setting custom properties (optional)

• AccessControl.UserView,
• AccessControl.UserModify,
• AccessControl.PropertyView,
• AccessControl.PropertyValueView,
• AccessControl.PropertyAllowedValueView,
• AccessControl.PropertyValueCreate,
• AccessControl.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1000

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "userState": "active",
  "version": 0,
  "loginId": "testUser",
  "languageCode": "en",
  "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,
    "locality": "Province XYZ"
  },
  "contacts": {
    "telephone": "+41781234567",
    "telefax": "+41781254154",
    "mobile": "+41781254156",
    "email": "[email protected]"
  },
  "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",
  "properties": {
    "custom_property1": "value1",
    "custom_property2": "value2"
  }
}

Response 200

• 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,
   "locality":"Province XYZ"
  },
  "contacts":{
    "telephone":"+41781234567",
    "telefax":"+41781254154",
   "mobile":"+41781254156",
   "email":"[email protected]"
 },
 "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

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.

since 2.79

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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyValue1",
  "propertyName2": "propertyValue2",
  "_classifications": {
    "personal": [
      "propertyName1",
      "propertyName2"
    ]
  }
}

Update user properties

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 has to contain an object of key-value property pairs.

Required permissions

• AccessControl.UserView,
• AccessControl.UserModify,
• AccessControl.PropertyView,
• AccessControl.PropertyValueView,
• AccessControl.PropertyAllowedValueView,
• AccessControl.PropertyValueCreate,
• AccessControl.PropertyValueDelete,
• AccessControl.PropertyValueModify

since 2.79

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1000/properties/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyNewValue1",
  "propertyName3": "propertyNewValue3"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyNewValue1",
  "propertyName2": "propertyValue2",
  "propertyName3": "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

Self-admin

Required permissions

• AccessControl.UserView,
• AccessControl.ProfileView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/100/profiles/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 100

  ExtID of the user.

Response 200

• 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": "1524579740000_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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 100

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1003",
  "unitExtId": "200",
  "deputedProfileExtId": "8566",
  "profileState": "active",
  "name": "something3",
  "isDefaultProfile": true,
  "remarks": "something3",
  "modificationComment": "none"
}

Response 201

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Response 204

Consents

A consent is the acceptance of a terms by a user.

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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "termsExtId": "1001"
}

Response 201

• Headers: Location: https://your-host/nevisidm/api/core/v1/1000/users/1000/consents/1001

Get Consents

GET /{clientExtId}/users/{extId}/consents/

Lists all consents accepted by a user determined by its client external ID and user external ID.

since 2.83.0

Required permissions

• AccessControl.ConsentView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1000/consents/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Response 200

• Headers: Content-Type: application/json
• Body:

[
  {
    "termsExtId": "ConsentGetRestTest1",
    "acceptanceDate": "2021-09-08T10:32:41Z",
    "termsVersion": "1.0"
  },
  {
    "termsExtId": "ConsentGetRestTest2",
    "acceptanceDate": "2021-09-08T10:32:41Z",
    "termsVersion": "1.1"
  }
]

Pending terms

Get pending terms

GET /{clientExtId}/users/{extId}/terms-pending/

Gets all the pending terms for a user.

Note that giving consent is not limited to the pending terms, a user can also give consent to terms which have no application assigned where a role is assigned to the user profile.

since 2.75.1

Required permissions

• AccessControl.ConsentView,
• AccessControl.TermsView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1000/terms-pending/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Request

• Headers: Content-Type: application/json

Response 200

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

Update login information

Update login information

POST /{clientExtId}/users/{extId}/login-info

Update user’s login information and if credential is present, then the credential’s login information as well.

Note that if credential is present, then it must exist, must belong to the user and must be active.

If credentialExtId is not present, then only the user’s login info is updated and the result code is 8, Unchecked.

since 2.88.0

Required permission

• AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1000/login-info

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "success": true,
  "credentialExtId": "user100credential100"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "statusCode": 5,
  "description": "Login Ok"
}

Response 404

• Headers: Content-Type: application/json
• Body:

{
  "errors": [
    {
      "code": "errors.noRecord",
      "message": "A user with extId fakeUserExtId doesn't exist on client with name Default"
    }
  ]
}

Response 404

• Headers: Content-Type: application/json
• Body:

{
  "errors": [
    {
      "code": "errors.noRecord",
      "message": "The requested credential 2454db8f-99ed-4562-a778-20ad76fdd566 is not belonging to client Default."
    }
  ]
}

Response 422

• Headers: Content-Type: application/json
• Body:

{
  "errors": [
    {
      "code": "errors.invalidParameter",
      "message": "The requested credential 28000000 is belonging to different user."
    }
  ]
}

Response 422

• Headers: Content-Type: application/json
• Body:

{
  "errors": [
    {
      "code": "errors.invalidParameter",
      "message": "The requested credential 36bee409-023a-460b-84a0-2a20ac372ae9 is not active."
    }
  ]
}

Credentials

Get user credentials

GET /{clientExtId}/users/{extId}/credentials

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

since 7.2405.0

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1000/credentials

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1000

  ExtID of the user.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "created": "2024-04-11T19:16:07Z",
      "lastModified": "2024-04-11T19:16:07Z",
      "version": 0,
      "createdBy": "Default/bootstrap",
      "modifiedBy": "Default/bootstrap",
      "lastChangeDate": "2024-04-11T19:16:07Z",
      "extId": "100",
      "userExtId": "100",
      "policyExtId": "100",
      "stateName": "active",
      "lastSuccessfulLoginDate": "2024-04-11T19:16:10Z",
      "successfulLoginCount": 1,
      "lastFailedLoginDate": "2024-04-11T19:16:10Z",
      "failedLoginCount": 2,
      "type": "PASSWORD",
      "validity": {
        "from": "2024-04-11T19:16:07Z",
        "to": "2030-01-01T00:00:00Z"
      },
      "resetCount": 0
    },
    {
      "created": "2024-04-11T20:11:45Z",
      "lastModified": "2024-04-11T20:11:45Z",
      "version": 1,
      "createdBy": "Default/bootstrap",
      "modifiedBy": "Default/bootstrap",
      "lastChangeDate": "2024-04-11T20:11:45Z",
      "extId": "99999994013",
      "userExtId": "100",
      "policyExtId": "105",
      "stateName": "disabled",
      "stateChangeReason": "initialized",
      "modificationComment": "",
      "type": "CERTIFICATE",
      "validity": {
        "from": "2024-04-11T20:11:45Z",
        "to": "2034-04-09T20:11:45Z"
      },
      "certificate": "N/A"
    },
    {
      "created": "2024-04-11T20:13:35Z",
      "lastModified": "2024-04-11T20:13:35Z",
      "version": 1,
      "createdBy": "Default/bootstrap",
      "modifiedBy": "Default/bootstrap",
      "lastChangeDate": "2024-04-11T20:13:35Z",
      "extId": "99999994015",
      "userExtId": "100",
      "stateName": "active",
      "stateChangeReason": "changed-by-admin",
      "modificationComment": "",
      "type": "Kerberos",
      "validity": {
        "from": "2024-04-11T20:13:35Z",
        "to": "2034-04-09T20:13:35Z"
      },
      "kerberosId": "kerberosId"
    }
  ],
  "_pagination": {
    "continuationToken": "1712859215000_99999994015",
    "limit": 1000
  }
}

Response 404

• Headers: Content-Type: application/json
• Body:

{
  "errors": [
    {
      "code": "errors.insufficientRightsFunction",
      "message": "Permission denied: Caller (callerUserId = 100) does not have the required right 'AccessControl.CredentialSearch' to perform this action"
    }
  ]
}

Response 404

• Headers: Content-Type: application/json
• Body:

{
  "errors": [
    {
      "code": "errors.noRecord",
      "message": "A user with extId 666 doesn't exist on client with name Default"
    }
  ]
}

Response 404

• Headers: Content-Type: application/json
• Body:

{
  "errors": [
    {
      "code": "errors.noRecord",
      "message": "Client doesn't exist with extId '777'"
    }
  ]
}

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 does not consider the roles assigned to profile B.

A profile has to 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 always have to set the target client.

Profile get DTO

The profile get DTO has the following parameters:

• extId - The external ID of the profile (string).
• userExtId - The external ID of the user to whom the profile belongs (string).
• unitExtId - The external ID of the unit to which the profile belongs (string).
• clientExtId - The external ID of the client to which the policy belongs (string).
• deputedProfileExtId - The external ID of the deputed profile (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 validity in ISO format (string).
  • to - End date of the profile 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).

Profile patch DTO

The profile patch DTO has the following parameters:

• name - The name of the profile (string).
• profileState - The state of the profile (string, default:active).
• 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 validity in ISO format (string).
  • to - End date of the profile validity in ISO format (string).
• version - Version used for optimistic locking (number).

Authorization create DTO

The authorization create DTO has the following parameters:

Mandatory

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

Optional

• extId - The external ID of the object.
• clientGlobal - Determines whether the authorization is applicable for the whole client (boolean).
• unitGlobal - Determines whether the authorization is restricted to a unit (boolean).
• appGlobal - Determines whether the authorization is restricted to an application (boolean).
• enterpriseRoleGlobal - Determines whether the authorization is restricted to an enterprise role (boolean).
• validity - Describes the validity period of the authorization (object).
  • from - Start date of the authorization validity in ISO format (string).
  • to - End date of the authorization validity in ISO format (string).

Authorization get DTO

The authorization get DTO has the following parameters:

• extId - The external ID of the object.
• roleExtId - The external ID of the connected role (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 validity in ISO format (string).
  • to - End date of the authorization 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).

Authorization patch DTO

The authorization patch DTO has the following parameters:

• clientGlobal - Determines whether the authorization is applicable for the whole client (boolean).
• unitGlobal - Determines whether the authorization is restricted to a unit (boolean).
• appGlobal - Determines whether the authorization is restricted to an application (boolean).
• enterpriseRoleGlobal - Determines whether the authorization is restricted to an enterprise role (boolean).
• validity - Describes the validity period of the authorization (object).
  • from - Start date of the authorization validity in ISO format (string).
  • to - End date of the authorization validity in ISO format (string).
• version - Version used for optimistic locking (number).

Application get DTO

The application get DTO has the following parameters:

• extId - External ID of the application (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 is to 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 (string).
• lastModified - Date when the entity was last modified (string).

Unit get DTO

The unit get DTO has the following parameters:

• extId - The external ID of the unit (string).
• parentUnitExtId - The external ID of the parent unit (string).
• clientExtId - The external ID of the client the unit belongs to (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 (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 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 validity period in ISO format (string).
  • to - The end date of the unit 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 (string).
• lastModified - Date when the entity was last modified (string).

Enterprise Authorization create DTO

The enterprise authorization create DTO has the following parameters:

Mandatory

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

Optional

• extId - The external ID of the object.
• validity - Describes the validity period of the authorization (object).
  • from - Start date of the authorization validity in ISO format (string).
  • to - End date of the authorization validity in ISO format (string).

Enterprise Authorization get DTO

The enterprise authorization get DTO has the following parameters:

• extId - The external ID of the object.
• enterpriseRoleExtId - The external ID of the enterprise role (string).
• validity - Describes the validity period of the authorization (object).
  • from - Start date of the authorization validity in ISO format (string).
  • to - End date of the authorization 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 Authorization patch DTO

The enterprise authorization patch DTO has the following parameters:

• validity - Describes the validity period of the authorization (object).
  • from - Start date of the authorization validity in ISO format (string).
  • to - End date of the authorization validity in ISO format (string).
• version - Version used for optimistic locking (number).

Enterprise role get DTO

The enterprise role get DTO has the following parameters:

• 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 get DTO

The role get DTO has the following parameters:

• extId - The external ID of the role (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 (string).
• lastModified - The date when the entity was last modified (string).

Property get DTO

The property get DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Property get DTO with classification

The property get DTO with classification has the following parameters:

• values - Property name-value pairs. (map<string, string>).
• _classifications - The defined classifications of the property (map<string, list>).

Property patch DTO

The property patch DTO has the following parameter:

• values - Property name-value pairs. (map<string, 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

Self-admin

Required permissions

• AccessControl.ProfileView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Response 200

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Request

• 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

• 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

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Request

• 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

• 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

Self-admin

Required permissions

• AccessControl.AuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Response 200

• 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": "1524579739000_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

Self-admin

Required permissions

• AccessControl.AuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/2001

URI Parameters

• 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

• 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

• 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

• 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

• 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

• 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

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 is overridden by properties with the scope onProfileForApp, if properties have the same key, that is, the same property name. Properties are additional, customer-specific attributes of an entity.

since 2.79

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

• 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

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyNewValue1",
  "propertyName3": "propertyNewValue3"
}

Update properties

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

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

since 2.79

Required permissions

• AccessControl.AuthorizationView,
• AccessControl.AuthorizationModify,
• AccessControl.PropertyView,
• AccessControl.PropertyValueView,
• AccessControl.PropertyAllowedValueView,
• AccessControl.PropertyValueCreate,
• AccessControl.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/profiles/1001/authorizations/2001/properties

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyNewValue1",
  "propertyName3": "propertyNewValue3",
  "propertyName4": ""
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyNewValue1",
  "propertyName2": "propertyValue2",
  "propertyName3": "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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• profileExtId: string (required) Example: 1001

  ExtID of the profile.

Request

• 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

• 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

Self-admin

Required permissions

• AccessControl.EnterpriseAuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eauthorizations/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• profileExtId: string (required) Example: 1001

  ExtID of the profile.

Response 200

• 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": "1524579740000_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

Self-admin

Required permissions

• AccessControl.EnterpriseAuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eauthorizations/2001

URI Parameters

• 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

• 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

• 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

• Headers: Content-Type: application/json
• Body:

{
  "version": 1,
  "validity": {
    "from": "2016-12-31T12:00:00Z",
    "to": "2024-01-01T12:00:00Z"
  }
}

Response 200

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

• 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

Self-admin

Required permissions

• AccessControl.AuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/roles

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Response 200

• 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": "1524579740000_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

Self-admin

Required permissions

• AccessControl.EnterpriseAuthorizationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/eroles

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Response 200

• 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": "1524579740000_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

Self-admin

Required permissions

• AccessControl.ProfileView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/unit

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Response 200

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

Assign 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

• 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

Self-admin

Required permissions

• AccessControl.ApplicationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/profiles/1001/applications

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Response 200

• 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": "1524579740000_1001",
    "limit": 100
  }
}

Profile properties

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.

since 2.79

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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyValue1",
  "propertyName2": "propertyValue2",
  "_classifications": {
    "personal": [
      "propertyName1",
      "propertyName2"
    ]
  }
}

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 has to contain an object of key-value property pairs.

since 2.79

Required permissions

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

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/profiles/1001/properties

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 1001

  ExtID of the profile.

Request

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyNewValue1",
  "propertyName3": "propertyNewValue3"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyName1": "propertyNewValue1",
  "propertyName2": "propertyValue2",
  "propertyName3": "propertyNewValue3",
  "_classifications": {
    "personal": [
      "propertyName1",
      "propertyName2"
    ]
  }
}

Identity REST Service

Identity REST Service can be used to create User and Profile with one call, including user properties.

Identity create DTO

The identity create DTO has the following parameters:

Mandatory

• user - A nested User Create DTO which has the following parameters:
  • extId - The external ID of the user. Can only be set on creation.
• profile - A nested Profile Create DTO which has the following parameters:
  • extId - The external ID of the profile. (read-only string).

Optional

• user - A nested User Create DTO which has the following parameters:
  • loginId - The login ID (username) of the user. Generated by the login id generator if the value is not provided and the generator is enabled (string).
  • userState - The state of the user (string, default:active).
  • 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, mandatory if validation.user.name.mandatory policy is set).
    • familyName - The last name of the user (string, mandatory if validation.user.firstname.mandatory policy is set).
  • sex - The biological sex of the user. This is not the same as legal gender (string, mandatory if validation.user.sex.mandatory policy is set).
  • 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 date of birth in ISO format (string).
  • address - The address of the user (object).
    • countryCode - The ISO country code of the user (string, mandatory if validation.user.country.mandatory policy is set).
    • 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 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).
    • locality - The locality of the user address (string).
  • contacts - Telephone numbers and email addresses on which the user can be contacted (object).
    • telephone - The number of the user landline (string, mandatory if validation.user.phone.regex policy is set).
    • telefax - The fax number of the user (string).
    • mobile - The cellphone number of the user (string, mandatory if validation.user.mobile.mandatory policy is set).
    • email - the email address of the user (string, mandatory if validation.user.email.mandatory policy is set).
  • validity - The validity period of the user entity (object).
    • to - The end date of the user validity period in ISO format (string).
    • from - The start date of the user validity period in ISO format (string).
  • remarks - General textual remark about the user (string).
  • modificationComment - Textual comment on the last modification (string).
• profile - A nested Profile Create DTO which has the following parameters:
  • unitExtId - The external ID of the unit to which the profile belongs (read-only string).
  • name - The name of the profile (string).
  • profileState - The state of the profile (string, default:active).
  • 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 validity in ISO format (string).
    • to - End date of the profile validity in ISO format (string).

Identity entities

Create identity

POST /{clientExtId}/identity/

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

since 2.85

Required permissions

• AccessControl.UserCreate,
• AccessControl.LoginIdOverride (for overriding the generated value of loginId generator, if enabled),
• AccessControl.UserCreateTechUser (for creating technical users only),
• AccessControl.ProfileCreate

Required permissions for setting custom properties (optional)

• AccessControl.UserView,
• AccessControl.UserModify,
• AccessControl.PropertyView,
• AccessControl.PropertyValueView,
• AccessControl.PropertyAllowedValueView,
• AccessControl.PropertyValueCreate,
• AccessControl.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/identity/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

Request

• Headers: Content-Type: application/json
• Body:

{
  "user": {
    "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,
      "locality": "Province XYZ"
    },
    "contacts": {
      "telephone": "+41781254153",
      "telefax": "+41781254154",
      "mobile": "+41781254156",
      "email": "[email protected]"
    },
    "validity": {
      "from": "2016-12-31T12:00:00Z",
      "to": "2022-01-01T12:00:00Z"
    },
    "remarks": "This is the new test user john doe",
    "modificationComment": "They live in ZH",
    "properties": {
      "custom_property1": "value1",
      "custom_property2": "value2"
    }
  },
  "profile": {
    "extId": "4254",
    "unitExtId": "1000",
    "profileState": "active",
    "name": "something",
    "isDefaultProfile": true,
    "remarks": "something",
    "modificationComment": "none",
    "validity": {
      "from": "2016-12-31T12:00:00Z",
      "to": "2022-01-01T12:00:00Z"
    }
  }
}

Response 201

• Headers: Location: https://your-host/nevisidm/api/core/v1/1000/users/4254

Application REST Service

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.

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

Application create DTO

The application create DTO has the following parameters:

Mandatory

• name - Internal name of the application (string).
• displayed - Determines whether the application is to be displayed on nevisPortal (boolean).

Optional

• extId - External ID of the application (string).
• description - Textual description of the application (string).
• url - URL of the application.
• 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).

Application get DTO

The application get DTO has the following parameters:

• extId - External ID of the application (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 is to 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 (string).
• lastModified - Date when the entity was last modified (string).

Application patch DTO

The application patch DTO has the following parameters:

• name - Internal name of the application (string).
• displayed - Determines whether the application is to be displayed on nevisPortal (boolean).
• description - Textual description of the application (string).
• url - URL of the application.
• 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).

Role get DTO

The role get DTO has the following parameters:

• extId - The external ID of the role (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 (string).
• lastModified - The date when the entity was last modified (string).

Role create DTO

The role create DTO has the following parameters:

Mandatory

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

Optional

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

Property get DTO

The property get DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Property patch DTO

The property patch DTO has the following parameter:

• values - Property name-value pairs. (map<string, 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

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1001",
  "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

• 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

Self-admin

Required permissions

• AccessControl.ApplicationView

Example URI

GET https://your-host/nevisidm/api/core/v1/applications/1001

URI Parameters

• extId: string (required) Example: 1001

  ExtID of the application.

Response 200

• 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

• extId: string (required) Example: 1001

  ExtID of the application.

Request

• 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

• 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

• 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

• extId: string (required) Example: 1001

  ExtID of the application.

Response 200

• 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": "1502928000000_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

• extId: string (required) Example: 1001

  ExtID of the application.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1020",
  "name": "readonlyRole",
  "description": "role of read-only users"
}

Response 201

• 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

• extId: string (required) Example: 1001

  ExtID of the application.

Request

• Headers: Content-Type: application/json

Response 200

• 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 has to contain an object of key-value property pairs.

since 2.74

Required permissions

• AccessControl.ApplicationView,
• AccessControl.ApplicationModify,
• AccessControl.PropertyView,
• AccessControl.PropertyValueView,
• AccessControl.PropertyAllowedValueView,
• AccessControl.PropertyValueCreate,
• AccessControl.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/applications/1001/properties/

URI Parameters

• extId: string (required) Example: 1001

  ExtID of the application.

Request

• Headers: Content-Type: application/json
• Body:

{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}

Response 200

• 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 parameters.

Only the name and description of a role are modifiable. Therefore, modification of a role parameters 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 get DTO

The role get DTO has the following parameters:

• extId - The external ID of the role (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 (string).
• lastModified - The date when the entity was last modified (string).

Role patch DTO

The role patch DTO has the following parameters:

• name - The name of the role (string).
• description - The textual description of the role (string).
• version - The version used for optimistic locking (number).

Property get DTO

The property get DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Property patch DTO

The property patch DTO has the following parameter:

• values - Property name-value pairs. (map<string, 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

• extId: string (required) Example: 231

  ExtID of the role.

Response 200

• 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

• extId: string (required) Example: 231

  ExtID of the role.

Request

• Headers: Content-Type: application/json
• Body:

{
  "version": 1,
  "name": "regularRole",
  "description": "regular role of normal users"
}

Response 200

• 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

• 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

• extId: string (required) Example: 232

  ExtID of the role.

Response 200

• 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 has to contain an object of of key-value property pairs.

since 2.74

Required permissions

• AccessControl.RoleView,
• AccessControl.RoleModify,
• AccessControl.PropertyView,
• AccessControl.PropertyValueView,
• AccessControl.PropertyAllowedValueView,
• AccessControl.PropertyValueCreate,
• AccessControl.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/roles/232/properties

URI Parameters

• extId: string (required) Example: 232

  ExtID of the role.

Request

• Headers: Content-Type: application/json
• Body:

{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
 "propertyKey1" : "propertyNewValue1",
 "propertyKey2" : "propertyValue2",
 "propertyKey3" : "propertyNewValue3",
}

Enterprise Role REST Service

An enterprise role defines a specific set of roles, for example, people with the same business function. It can be assigned to multiple user 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 affects 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 have to 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 always have to set the target client.

Enterprise role create DTO

The enterprise role create DTO has the following parameters:

Mandatory

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

Optional

• extId - The external ID 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).

Enterprise role get DTO

The enterprise role get DTO has the following parameters:

• 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).

Enterprise role patch DTO

The enterprise role patch DTO has the following parameters:

• 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).

Role get DTO

The role get DTO has the following parameters:

• extId - The external ID of the role (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 (string).
• lastModified - The date when the entity was last modified (string).

Property get DTO

The property get DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Property patch DTO

The property patch DTO has the following parameter:

• values - Property name-value pairs. (map<string, 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "2345",
  "name": "erole1",
  "description": "erole1",
  "displayName": {
    "EN": "erole1",
    "DE": "erole1",
    "FR": "erole1",
    "IT": "erole1"
  }
}

Response 201

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• eroleExtId: string (required) Example: 2345

  ExtID of the enterprise role.

Response 200

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• eroleExtId: string (required) Example: 2345

  ExtID of the enterprise role.

Request

• Headers: Content-Type: application/json
• Body:

{
  "version": 2,
  "name": "erole1",
  "description": "erole1",
  "displayName": {
    "EN": "erole1",
    "DE": "erolle1",
    "FR": "erole1",
    "IT": "erole1"
  }
}

Response 200

• 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

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• eroleExtId: string (required) Example: 2345

  ExtID of the enterprise role.

Response 200

• 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": "1524579619000_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

• 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

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• eroleExtId: string (required) Example: 2345

  ExtID of the enterprise role.

Response 200

• 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 has to 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.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/eroles/2345/properties/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• eroleExtId: string (required) Example: 2345

  ExtID of the enterprise role.

Request

• Headers: Content-Type: application/json
• Body:

{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
 "propertyKey1" : "propertyNewValue1",
 "propertyKey2" : "propertyValue2",
 "propertyKey3" : "propertyNewValue3",
}

Policy REST Service

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.

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 always have to set the target client.

Policy get DTO

The policy get DTO has the following parameters:

• extId - The external ID of the policy (string).
• clientExtId - The external ID of the client to which the policy belongs (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 (string).

Policy patch DTO

The policy patch DTO has the following parameters:

• name - The name of the policy (string).
• description - The textual description of the 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).

Policy create DTO

The policy create DTO has the following parameters:

Mandatory

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

Optional

• extId - The external ID of the policy (string).
• description - The textual description of the 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).

Policies

Create policy

POST /{clientExtId}/policies/

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

since 2.79

Required permissions

• AccessControl.PolicyConfigurationCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/policies/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "99990049",
  "description": "PDF Email Policy",
  "name": "TicketPolicyForPDFEmailSending",
  "policyType": "TicketPolicy",
  "defaultPolicy": true,
  "parameters": {
    "param1": "value1",
    "param2": "value2",
    "paramN": "valueN"
  }
}

Response 201

• 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.79

Required permissions

• AccessControl.PolicyConfigurationView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/policies/99990049

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 99990049

  ExtID of the policy.

Response 200

• 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.79

Required permissions

• AccessControl.PolicyConfigurationDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/policies/99990049

URI Parameters

• 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.79

Required permissions

• AccessControl.PolicyConfigurationView,
• AccessControl.PolicyConfigurationModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/policies/99990049

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 99990049

  ExtID of the policy.

Request

• Headers: Content-Type: application/json
• Body:

{
  "description": "PDF Email Policy",
  "name": "TicketPolicyForPDFEmailSending",
  "defaultPolicy": true,
  "version": 0,
  "parameters": {
    "param1": "value1",
    "param2": "value2new",
    "paramN": "valueN"
  }
}

Response 200

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

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 parameters:

• 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 parameters:

Mandatory

• 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).

Optional

• extId - The external id of the Terms object (string).
• urls - Actual Terms and Conditions pages (string).

Terms patch DTO

The terms patch DTO has the following parameters:

• 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

• 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

• 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

• 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

• extId: string (required) Example: 250000003

  ExtID of the terms.

Response 200

• 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

• extId: string (required) Example: 250000003

  ExtID of the terms.

Request

• Headers: Content-Type: application/json
• Body:

{
  "name": "termsName",
  "active": true,
  "termsVersion": "termsVersion",
  "version": 1,
  "urls": {
    "de": "https://www.sampleUrl.terms",
    "fr": "https://www.sampleUrl2.terms"
  }
}

Response 200

• 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

• extId: string (required) Example: 250000003

  ExtID of the terms.

Response 204

• 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

• termsExtId: string (required) Example: 250000003

  ExtID of the terms.

• applicationExtId: string (required) Example: 26000001

  ExtId of the application.

Response 204

• 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

• termsExtId: string (required) Example: 250000003

  ExtID of the terms.

• applicationExtId: string (required) Example: 26000001

  ExtId of the application.

Response 204

• Headers: Content-Type: application/json

Certificate REST Service

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

Certificate create DTO

The certificate create DTO has the following parameters:

Mandatory

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

Optional

• 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, default:initial).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED

Certificate get DTO

The certificate get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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 validity in ISO format (string).
  • to - End date of the profile 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).

Certificate patch DTO

The certificate patch DTO has the following parameters:

• certificate - The certificate value of the credential (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• modificationComment - Textual comment regarding the last modification (string).
• version - Version used for optimistic locking (number).

Property get DTO

The property get DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Property patch DTO

The property patch DTO has the following parameter:

• values - Property name-value pairs. (map<string, string>).

Certificates

Create certificate

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

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

since 2.71

Self-admin

Required permissions

• AccessControl.CredentialCreate,
• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "4254",
  "policyExtId": "104",
  "stateName": "active",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIID5TCCA....8aLpcd+Q=\n-----END CERTIFICATE-----"
}

Response 201

• 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

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• 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": "[email protected], 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": "1533600000000_39250001",
    "limit": 1000
  }
}

Certificate

Get certificate

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

Returns the certificate credential with the given external ID.

since 2.71

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033

URI Parameters

• 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

• 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

Self-admin

Required permissions

• AccessControl.CredentialModify,
• AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "certificate": "-----BEGIN CERTIFICATE-----\nMIID5TCCA....8aLpcd+Q=\n-----END CERTIFICATE-----",
  "stateName": "active",
  "modificationComment": "changed-by-admin",
  "version": 5
}

Response 200

• 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

Self-admin

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033

URI Parameters

• 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

• 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

• 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

• 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 has to 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.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/certificates/28000033/properties/

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyKey1": "propertyNewValue1",
  "propertyKey2": "propertyValue2",
  "propertyKey3": "propertyNewValue3"
}

Context Password REST Service

Context Password get DTO

The Context Password get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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, for example, 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 parameter of context password credential (string).
• validity - Describes the validity period of the credential (object).
  • from - Start date of the profile validity in ISO format (string).
  • to - End date of the profile 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).
• 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 create DTO has the following parameters:

Mandatory

• context - The value of the context parameter of context password credential (string).

Optional

• extId - The external ID of the credential (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string, default:initial).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• password - The value of the context password credential. This parameter is never returned (string).

Context Password patch DTO

The context password patch DTO has the following parameters:

• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• 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 parameter:

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

Context Password change DTO

The password change DTO has the following parameters:

Mandatory

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

Optional

• oldPassword - The old password. This parameter has to be omitted when the caller changes the password of someone else (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. Otherwise, 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 27000029

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1001",
  "policyExtId": "201",
  "stateName": "active",
  "password": "secretpassword",
  "context": "context"
}

Response 201

• 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

Self-admin

Required permissions

• AccessControl.CredentialView

Technical parameters limitation

The createdBy and modifiedBy parameters hold the Login ID of the user when they created or 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• 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": "1533600000000_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

Self-admin

Required permissions

• AccessControl.CredentialView

#### Technical parameters limitation

The createdBy and modifiedBy parameters hold the Login ID of the user when they created or 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

• 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

• 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

• 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

• 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.

Self-admin

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

• 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

• Headers: Content-Type: application/json
• Body:

{
  "stateName": "active",
  "modificationComment": "no comment",
  "version": 2
}

Response 200

• 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

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 parameter passwordFragment or no content is returned.

since 2.79

Self-admin

Required permissions

• AccessControl.CredentialView,
• AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/context-passwords/27000030/reset

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "passwordFragment": "s2323dW"
}

Response 204

• 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 parameter in the request body is mandatory if a caller wants to change his own password. If the caller wants to change the password of another user, the oldPassword parameter in the request body has to be omitted.

since 2.73

Self-admin

Required permissions

• AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/context-passwords/5678/change

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "oldPassword": "oldPassword",
  "newPassword": "newSecretPassword"
}

Response 204

• Headers: Content-Type: application/json

FIDO2 REST Service

The FIDO2 Service is used to manage the FIDO2 credentials.

FIDO2 external IDs are unique per client only, not globally. Therefore, you always have to set the target client.

FIDO2 create DTO

The FIDO2 create DTO has the following parameters:

Mandatory

• authenticator - The authenticator used for FIDO2 which can contains credentialId (string).
• aaguid - A 128-bit identifier indicating the type (for example, make and model) of the authenticator (string).
• hashedCredentialId - The hashed value of credential ID generated by the authenticator (string).
• rpId - The domain of the party who uses this authentication for its website (string).
• residentKeyRequirement - The value of authenticator’s ResidentKey parameter, which is contains if the server is willing to store private keys, possible values are ‘required’ and ‘discouraged’ (string).
• attestationConveyancePreference - The value of authenticator’s AuthenticatorAttachment parameter, possible values are ‘direct’, ‘indirect’, ‘none’ and ‘enterprise’ (string).
• userVerificationRequirement - Contains the value of the authenticator User Verification parameter, which decides which process is used for verification. Possible values are: ‘required’, ‘preferred’ and ‘discouraged’ (string).

Optional

• authenticatorAttachment - The value of authenticator’s AuthenticatorAttachment parameter, possible values are ‘platform’ and ‘crossplatform’ (string).
• extId - The external ID (string).
• stateName - The state of the credential (string, default:active).
  • Available values:
    • ACTIVE,
    • DISABLED
• userAgent - UserAgent of the browser used (string).
• userFriendlyName - Human readable name of the credential (string).

FIDO2 get DTO

The FIDO2 get DTO has the following parameters:

• extId - The external ID of the credential (string).
• userExtId - The external ID of the user to whom the credential belongs (string).
• aaguid - A 128-bit identifier indicating the type (for example, make and model) of the authenticator (string).
• authenticator - The authenticator used for FIDO2 which can contains credentialId (string).
• hashedCredentialId - The hashed value of credential ID generated by the authenticator (string).
• rpId - The domain of the party who uses this authentication for its website (string).
• authenticatorAttachment - The value of authenticator’s AuthenticatorAttachment parameter, possible values are ‘platform’ and ‘crossplatform’ (string).
• attestationConveyancePreference - The value of authenticator’s AuthenticatorAttachment parameter, possible values are ‘direct’, ‘indirect’, ‘none’ and ‘enterprise’ (string).
• residentKeyRequirement - The value of authenticator’s ResidentKey parameter, which is contains if the server is willing to store private keys, possible values are ‘required’ and ‘discouraged’ (string).
• stateName - The state of the credential (string, default:active).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• userAgent - UserAgent of the browser used (string).
• userFriendlyName - Human readable name of the credential (string).
• userVerificationRequirement - Contains the value of the authenticator User Verification parameter, which decides which process is used for verification. Possible values are: ‘required’, ‘preferred’ and ‘discouraged’ (string).
• type - The type 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 (string).
• lastModified - Date when the entity was last modified (string).

FIDO2 patch DTO

The FIDO2 patch DTO has the following parameters:

• authenticator - The authenticator used for FIDO2 which can contains credentialId (string).
• userFriendlyName - Human readable name of the credential (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• modificationComment - Textual comment regarding the last modification (string).
• version - Version used for optimistic locking (number).

FIDO2 Credentials

Create FIDO2 Credential

POST /{clientExtId}/users/{userExtId}/fido2

Creates a FIDO2 credential for the user with the given external ID.

since 2.86

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/fido2

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "fidoTestExtId",
  "aaguid": "cb69481e-8ff7-4039-93ec-0a2729a154a8",
  "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a707150622e706e67",
  "authenticatorAttachment": "platform",
  "attestationConveyancePreference": "direct",
  "hashedCredentialId": "YmqcB3lo1skz629IIiYauEzEdGnxjq+XHgMYryTmgV3w6eM9+5JUcGwn2hJB0whyh9wI+ib7mg8HbshNKmE0A==",
  "rpId": "siven.ch",
  "residentKeyRequirement": "required",
  "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
  "userFriendlyName": "NEVIS Android phone",
  "userVerificationRequirement": "required",
  "stateName": "active"
}

Response 201

• Headers: Content-Type: application/json

Get user FIDO2 credentials

GET /{clientExtId}/users/{userExtId}/fido2

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

since 2.86

Self-admin

Filter

The results can be filtered by userFriendlyName and stateName.

Example of filtering

http://localhost:8080/nevisidm/api/core/v1/100/users/1234/fido2?userFriendlyName=NEVIS Android phone&stateName=active

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/fido2

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "created": "2021-11-24T17:00:40Z",
      "lastModified": "2021-11-24T17:00:40Z",
      "version": 2,
      "extId": "fido2TestExtId",
      "userExtId": "1234",
      "aaguid": "cb69481e-8ff7-4039-93ec-0a2729a154a8",
      "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a707150622e706e67",
      "authenticatorAttachment": "platform",
      "attestationConveyancePreference": "direct",
      "hashedCredentialId": "YmqcB3lo1skz629IIiYauEzEdGnxjq+XHgMYryTmgV3w6eM9+5JUcGwn2hJB0whyh9wI+ib7mg8HbshNKmE0A==",
      "rpId": "siven.ch",
      "residentKeyRequirement": "required",
      "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
      "userFriendlyName": "NEVIS Android phone",
      "userVerificationRequirement": "required",
      "stateName": "active",
      "type": "FIDO2 Authenticator",
      "validity": {
        "from": "2021-11-24T17:00:40Z",
        "to": "2031-11-22T17:00:40Z"
      }
    },
    {
      "created": "2021-11-24T17:00:41Z",
      "lastModified": "2021-11-24T17:00:41Z",
      "version": 2,
      "extId": "fido2TestExtId2",
      "userExtId": "1234",
      "aaguid": "cb69481e-8ff7-4039-93ec-0a2729a154a7",
      "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a707150622e706e67",
      "authenticatorAttachment": "platform",
      "attestationConveyancePreference": "direct",
      "hashedCredentialId": "YmqcB3lo1skz629IIiYauEzEdGnxjq+XHgMYryTmgV3w6eM9+5JUcGwn2hJB0whyh9wI+ib7mg8HbshNKmE0A==",
      "rpId": "siven.ch",
      "residentKeyRequirement": "required",
      "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
      "userFriendlyName": "NEVIS Android phone",
      "userVerificationRequirement": "required",
      "stateName": "active",
      "type": "FIDO2 Authenticator",
      "validity": {
        "from": "2021-11-24T17:00:41Z",
        "to": "2031-11-22T17:00:41Z"
      }
    }
  ],
  "_pagination": {
    "continuationToken": "1637769641280_fido2TestExtId2",
    "limit": 1000
  }
}

FIDO2 Credentials

Get FIDO2

GET /{clientExtId}/users/{userExtId}/fido2/{extId}

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

since 2.86

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/fido2/28000002

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "created": "2021-11-24T16:48:08Z",
  "lastModified": "2021-11-24T16:48:08Z",
  "version": 2,
  "extId": "28000002",
  "userExtId": "1234",
  "aaguid": "cb69481e-8ff7-4039-93ec-0a2729a154a8",
  "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a707150622e706e67",
  "authenticatorAttachment": "platform",
  "attestationConveyancePreference": "direct",
  "hashedCredentialId": "YmqcB3lo1skz629IIiYauEzEdGnxjq+XHgMYryTmgV3w6eM9+5JUcGwn2hJB0whyh9wI+ib7mg8HbshNKmE0A==",
  "rpId": "siven.ch",
  "residentKeyRequirement": "required",
  "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
  "userFriendlyName": "NEVIS Android phone",
  "userVerificationRequirement": "required",
  "stateName": "active",
  "type": "FIDO2 Authenticator",
  "validity": {
    "from": "2021-11-24T16:48:08Z",
    "to": "2031-11-22T16:48:08Z"
  }
}

Update FIDO2

PATCH /{clientExtId}/users/{userExtId}/fido2/{extId}

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

since 2.86

Self-admin

Required permissions

• AccessControl.CredentialView,
• AccessControl.CredentialModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/fido2/28000002

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a327150622e706d67",
  "userFriendlyName": "newName",
  "stateName": "disabled",
  "modificationComment": "Modification Comment",
  "version": 0
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "created": "2021-11-26T15:25:43Z",
  "lastModified": "2021-12-03T11:49:52Z",
  "version": 1,
  "extId": "fido2AdminAllSet",
  "userExtId": "250002034",
  "aaguid": "cb69481e-8ff7-4039-93ec-0a2729a154a8",
  "authenticator": "a56d7270446973706c61794e616d656441636d656b646973706c61794e616d656d4a6f686e20502e20536d697468646e616d65766a6f686e70736d697468406578616d706c652e636f6d626964703130393832333732333534303938373268696d61676555524c782868747470733a2f2f706963732e61636d652e636f6d2f30302f702f61426a6a6a327150622e706d67",
  "authenticatorAttachment": "platform",
  "attestationConveyancePreference": "direct",
  "hashedCredentialId": "YmqcB3lo1skz629IIiYauEzEdGnxjq+XHgMYryTmgV3w6eM9+5JUcGwn2hJB0whyh9wI+ib7mg8HbshNKmE0A==",
  "rpId": "siven.ch",
  "residentKeyRequirement": "required",
  "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
  "userFriendlyName": "newName",
  "userVerificationRequirement": "required",
  "stateName": "disabled",
  "type": "FIDO2 Authenticator",
  "modificationComment": "Modification Comment",
  "validity": {
    "from": "2021-11-26T15:25:43Z",
    "to": "2031-11-24T15:25:43Z"
  }
}

Delete FIDO2

DELETE /{clientExtId}/users/{userExtId}/fido2/{extId}

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

since 2.86

Self-admin

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/fido2/28000002

URI Parameters

• 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

• Headers: Content-Type: application/json

FIDO UAF REST Service

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

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

Fido UAF create DTO

The FIDO UAF create DTO has the following parameters:

Mandatory

• 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).

Optional

• extId - The external ID (string).
• deviceId - The device identifier obtained from a push service (string).
• dispatchTargetExtId - In contrast with the deviceId this field can guarantee a unique 1:N association between the dispatch target and the UAF credential (string).
• stateName - The state of the credential (string, default:active).
  • Available values:
    • ACTIVE,
    • DISABLED
• policyExtId - The external ID of the used policy (string).
• validity - Describes the validity period of the credential (object).
  • from - Start date of the credential validity in ISO format (string).
  • to - End date of the credential validity in ISO format (string).

Fido UAF get DTO

The FIDO UAF get DTO has the following parameters:

• 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).
  • Available values:  ACTIVE,  DISABLED
• 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 validity in ISO format (string).
  • to - End date of the profile 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).
• policyExtId - The external ID of the used policy (string).
• dispatchTargetExtId - In contrast with the deviceId this field can guarantee a unique 1:N association between the dispatch target and the UAF credential (string).

Fido UAF patch DTO

The FIDO UAF patch DTO has the following parameters:

Mandatory

• 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).
  • Available values:
    • ACTIVE,
    • DISABLED
• modificationComment - Textual comment regarding the last modification (string).
• version - Version used for optimistic locking (number).

Optional

• policyExtId - The external ID of the used policy (string).
• validity - Describes the validity period of the credential (object).
  • from - Start date of the credential validity in ISO format (string).
  • to - End date of the credential validity in ISO format (string).
• dispatchTargetExtId - In contrast with the deviceId this field can guarantee a unique 1:N association between the dispatch target and the UAF credential (string).

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

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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• 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"
 "validity": {
     "from": "2018-07-21T19:03:49Z",
    "to": "2028-07-18T19:03:49Z"
 },
 "policyExtId": "fidoUafPolicyExtId"
}

Response 201

• 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,
  "policyExtId": "fidoUafPolicyExtId"
}

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

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• 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": 1,
      "policyExtId": "fidoUafPolicyExtId"
    },
    {
      "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,
      "policyExtId": "fidoUafPolicyExtId"
    }
  ],
  "_pagination": {
    "continuationToken": "1376697600000_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

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators/28000002

URI Parameters

• 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

• 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,
  "policyExtId": "fidoUafPolicyExtId"
}

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

Self-admin

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators/28000002

URI Parameters

• 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

• 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

Self-admin

Required permissions

• AccessControl.CredentialView,
• AccessControl.CredentialModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/fido-authenticators/28000002

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
 "signCounter": 0,
 "appId": "abc",
 "deviceId": "deviceId",
 "stateName": "active",
 "modificationComment": "changed-by-admin",
 "version": 2
 "validity": {
    "from": "2018-07-21T19:03:49Z",
    "to": "2028-07-18T19:03:49Z"
  },
  "policyExtId": "fidoUafPolicyExtId"
}

Response 200

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

Generic Credential REST Service

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

Generic credential get DTO

The generic credential get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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, for example, 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 validity in ISO format (string).
  • to - End date of the profile 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).
• properties - Custom properties of the credential (map<string, string>).

Generic credential create DTO

The generic credential create DTO has the following parameters:

Mandatory

• identification - The identification of the generic credential (string).

Optional

• extId - The external ID of the credential (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string, default:initial).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• properties - Custom properties of the credential (map<string, string>).
• validity - The validity period of the generic credential (object).
  • to - The end date of the user validity period in ISO format (string).
  • from - The start date of the user validity period in ISO format (string).

Generic credential patch DTO

The generic credential patch DTO has the following parameters:

• identification - The identification of the generic credential (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• modificationComment - Textual comment regarding the last modification (string).
• version - Version used for optimistic locking (number).

Property get DTO

The property get DTO has the following parameter:

• values - Property name-value pairs (map<string, string>).

Property patch DTO

The property patch DTO has the following parameter:

• values - Property name-value pairs. (map<string, 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. Custom properties may be returned with the credential, but if the caller does not have the right to access them, then they are simply omitted from the DTO.

since 2.73

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/generic-credentials/1234

URI Parameters

• 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

• 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,
  "properties": {
    "custom_property1": "value1",
    "custom_property2": "value2"
  }
}

Get 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

Self-admin

Required permissions

• AccessControl.CredentialView,
• AccessControl.CredentialModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/generic-credentials/1234

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "policyExtId": "6789",
  "stateName": "initial",
  "identification": "identification",
  "modificationComment": "changed",
  "version": 4
}

Response 200

• 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,
  "properties": {
    "custom_property1": "value1",
    "custom_property2": "value2"
  }
}

Delete Generic Credential

DELETE /{clientExtId}/users/{userExtId}/generic-credentials/{extId}

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

Self-admin

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

• 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

• 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

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/250002047/generic-credentials/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 250002047

  ExtID of the user.

Response 200

• 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,
      "properties": {
        "custom_property1": "value1",
        "custom_property2": "value2"
      }
    },
    {
      "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,
      "properties": {
        "custom_property1": "value3",
        "custom_property2": "value4"
      }
    },
    {
      "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,
      "properties": {
        "custom_property3": "value3",
        "custom_property2": "value2"
      }
    }
  ],
  "_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. While it is also possible to set the custom properties for the credential in the very same call, note that this call does not create new custom properties, only custom property values.

since 2.73

Required permissions

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

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/250002047/generic-credentials/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 250002047

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
 "extId": "4500",
 "policyExtId": "6789",
 "identification": "someIdentification",
 "stateName": "active",
 "properties":
 {
   "custom_property1": "value1",
   "custom_property2": "value2"
 },
 "validity": {
   "from": "2000-01-01T00:00:00Z",
   "to": "2050-01-01T00:00:00Z"
 },
}

Response 201

• 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

Self-admin

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

• 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

• 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 has to 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.PropertyValueDelete,
• AccessControl.PropertyValueModify

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/generic-credentials/28000033/properties/

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "propertyKey1": "propertyNewValue1",
  "propertyKey3": "propertyNewValue3"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "propertyKey1": "propertyNewValue1",
  "propertyKey2": "propertyValue2",
  "propertyKey3": "propertyNewValue3"
}

Kerberos REST Service

The Kerberos REST Service is used to manage the Kerberos credentials.

Kerberos external IDs are unique per client only, not globally. Therefore, you always have to set the target client.

Kerberos create DTO

The Kerberos create DTO has the following parameters:

Mandatory

• kerberosId - The identifier of the Kerberos credential (string).

Optional

• extId - The external ID of the Kerberos credential (string).
• stateName - The state of the credential (string, default:active).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED

Kerberos get DTO

The kerberos credential get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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 validity in ISO format (string).
  • to - End date of the profile 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).

Kerberos patch DTO

The kerberos credential patch DTO has the following parameters:

• kerberosId - The external ID used to map the user to the SAM account (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• 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.

since 2.79

Required permissions

• AccessControl.CredentialCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "kerberosExtId",
  "kerberosId": "someKerberosId",
  "stateName": "active"
}

Response 201

• 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.

since 2.79

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json

Response 200

• 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": {
    "continuationToken": "1533592800000_250002052",
    "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.

since 2.79

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/1234/

URI Parameters

• 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

• Headers: Content-Type: application/json

Response 200

• 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.

since 2.79

Self-admin

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/1234/

URI Parameters

• 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

• 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.

since 2.79

Required permissions

• AccessControl.CredentialModify,
• AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/kerberos/1234/

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "kerberosId": "user-login-ID-1@windows-domain",
  "stateName": "active",
  "modificationComment": "Update kerberos comment",
  "version": 4
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "created": "2018-08-07T00:00:00Z",
  "lastModified": "2018-08-07T00:00:00Z",
  "version": 5,
  "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"
  }
}

Mobile Authentication REST Service

mAuth REST Service is used to manage Mobile Authentication credentials.

Mobile authentication credential get DTO

The mobile authentication get DTO has the following parameters:

• extId - The external ID of the credential (string).
• name - The name of the credential (string).
• created - Creation date of the entity (string).
• stateName - The state of the credential.
  • Available values:
    • ACTIVE,
    • DISABLED based on the state of the generic credential and the underlying FIDO UAF credentials (string).

Mobile authentications

Get mobile authentications

GET /{clientExtId}/users/{userExtId}/mauths/

Returns credentials of the user with the given external ID, which have the fidouaf_signature_key property set for the credential. Fido UAF credentials not included.

since 2.77

Self-admin

Filter

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/mauths/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "extId": "015",
      "name": "personal iPhone",
      "created": "2020-03-26T09:50:18.214Z",
      "stateName": "initial"
    },
    {
      "extId": "003",
      "name": "company Android",
      "created": "2019-02-24T12:50:37.214Z",
      "stateName": "active"
    }
  ]
}

Count mobile authentications

Count mobile authentications

GET /{clientExtId}/users/{userExtId}/mauths/count/

Returns the count of credentials of the user with the given external ID, which have the fidouaf_signature_key property set for the credential.

since 2.81

Filter

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/100/mauths/count/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 100

  ExtID of the user.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "count": 1
}

Mobile authentication

Delete mobile authentication

DELETE /{clientExtId}/users/{userExtId}/mauths/{mauthExtId}/

Deletes a mobile authentication credential of the user.

since 2.77

Self-admin

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/100/mauths/100/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 100

  ExtID of the user.

• mauthExtId: string (required) Example: 100

  ExtID of the mobile auth credential.

Response 204

• Headers: Content-Type: application/json

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 always have to set the target client.

mTAN create DTO

The mTAN credential create DTO has the following parameters:

Mandatory

• mobileNumber - The mobile number in E164 format to associate with the mTan credential (string).

Optional

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

mTAN get DTO

The mTAN credential get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• 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 validity in ISO format (string).
  • to - End date of the profile 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).

mTAN patch DTO

The mTAN credential patch DTO has the following parameters:

• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "mTanExtId",
  "mobileNumber": "+41442726111",
  "policyExtId": "6789"
}

Response 201

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json

Response 200

• 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": {
        "continuationToken": "1533592800000_250002052",
        "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

• 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

• Headers: Content-Type: application/json

Response 200

• 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

• 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

• Headers: Content-Type: application/json
• Body:

{
  "stateName": "active",
  "modificationComment": "Update mTAN comment",
  "version": 4
}

Response 200

• 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.

Self-admin

since 2.74

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/mtans/1234/

URI Parameters

• 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

• Headers: Content-Type: application/json

Update mTAN login information

POST /{clientExtId}/users/{userExtId}/mtans/{extId}/

Updates the login information of the mTAN credential with the given external ID, belonging to the user with the given external ID.

since 2.86

Required permissions

• AccessControl.CredentialModify,
• AccessControl.CredentialView

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/mtans/1234/

URI Parameters

• 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

• Headers: Content-Type: application/json
• Body:

{
  "success": true
}

Response 200

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

OATH REST Service

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

OATH get DTO

The OATH credential get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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, for example, 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 validity in ISO format (string).
  • to - End date of the profile 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).

OATH create DTO

The OATH credential create DTO has the following parameters:

Mandatory

• label - The label of the OATH credential (string).

Optional

• extId - The external ID of the credential (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string, default:active).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED

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

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/oath-credentials/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• 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": "1502920800000_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

Self-admin

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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "4500",
  "policyExtId": "6789",
  "label": "label",
  "stateName": "initial"
}

Response 201

• 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

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/oath-credentials/4321

URI Parameters

• 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

• 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

Self-admin

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/oath-credentials/4321

URI Parameters

• 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

• Headers: Content-Type: application/json

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 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 always has to belong to a user. It cannot be reassigned to someone else.

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

Password create DTO

The password create DTO has the following parameters:

Optional

• 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, default:initial).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• password - The value of the password credential. This parameter 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 parameter:

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

Password change DTO

The password change DTO has the following parameters:

Mandatory

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

Optional

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

Password get DTO

The Password get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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, for example, 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 validity in ISO format (string).
  • to - End date of the profile 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).
• 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 parameters:

• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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 contains a part of the generated password, in the parameter passwordFragment.

In case the password creation fails, because the provided password violates any password policies, all the related policies will be included in the error message, where:

• displayName: the name of the password policy. For example allowLoginIdInPassword. The compete list can be found in the Configuration > Credentials > Policy parameters > Password chapter of the reference guide.
• configString: a representation of the rule in the policy. For example:
  • for policies like minHistoryTime, this is minimal time needed by the policy, in milliseconds.
  • for policies checking regular expressions, this is the regexp itself.
  • for most of the policies this field is empty.
• suppliedValue: this is the value of the credential, the password supplied.
• limitValue: this is the numerical value, that the policy checks. For example a regular expression based policy may check how many times does its regular expression match the given input.
• actualValue: this is the value, that the policy checks against. For limit based policies, this is the value not matching the limit.

For more details

since 2.71

Required permissions

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

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/password

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1001",
  "policyExtId": "100",
  "stateName": "active",
  "password": "secretpassword"
}

Response 204

• Headers: Content-Type: application/json

Response 201

• Headers: Content-Type: application/json
• Body:

{
  "passwordFragment": "A31S@ass"
}

Response 422

• Headers: Content-Type: application/json
• Body:

{
  "errors": [
    {
      "code": "errors.pwdPolicyViolated",
      "message": "Policy failed:ch.nevis.idm.policy.element.PolicyElementViolation<element=Regex policy violation limit=5, displayName=minLength, configurationString=., actualValue=3>"
    }
  ],
  "policyViolations": [
    {
      "displayName": "minLength",
      "configString": ".",
      "suppliedValue": "123",
      "limitValue": 5,
      "actualValue": "3"
    }
  ]
}

Get Password

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

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

since 2.71

Self-admin

Required permissions

• AccessControl.CredentialView

Technical parameters limitation

The createdBy and modifiedBy parameters hold the Login ID of the user when they created or 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/password

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
 "stateName": "active",
 "modificationComment": "modified",
 "version": 0,
}

Response 200

• 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.

Self-admin

since 2.73

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/password

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 204

• 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 parameter in the request body is mandatory if a caller wants to change his own password. If the caller wants to change the password of another user, the oldPassword parameter in the request body has to be omitted.

since 2.71

Self-admin

Required permissions

• AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/password/change

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "oldPassword": "oldPassword",
  "newPassword": "newSecretPassword"
}

Response 204

• Headers: Content-Type: application/json

Password Reset

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 parameter passwordFragment, or no content is returned. Changes the state of the credential to initial.

since 2.78

Self-admin

Required permissions

• AccessControl.CredentialView,
• AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/password/reset

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 201

• Headers: Content-Type: application/json
• Body:

{
  "passwordFragment": "s2323dW"
}

Response 204

• Headers: Content-Type: application/json

Password Unlocking

Unlock Password

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

Unlocks the password of the user with the given external ID. No content is returned. Changes the state of the credential to active and resets the failedLoginCount and successfulLoginCount to 0.

since 2.78

Required permissions

• AccessControl.CredentialView,
• AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/password/unlock

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 204

• Headers: Content-Type: application/json

Personal Question REST Service

Personal Question create DTO

The personal question create DTO has the following parameters:

Mandatory

• stateName - The state of the credential (string).
  • Available values:
    • ACTIVE,
    • DISABLED,
    • ARCHIVED

Optional

• extId - The external ID of the personal question (string).
• description - The textual description of the personal question (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 get DTO

The personal question get DTO has the following parameters:

• extId - The external ID of the personal question (string).
• clientExtId - The external ID of the client to which the personal question belongs (string).
• description - The textual description of the personal question (string).
• stateName - The state of the credential (string).
  • Available values:
    • ACTIVE,
    • DISABLED,
    • ARCHIVED
• 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)  version - Version used for optimistic locking (number).  created - Creation date of the entity (string). * lastModified - Date when the entity was last modified (string).

Personal Question patch DTO

The personal question patch DTO has the following parameters:

• version - Version used for optimistic locking (number).
• description - The textual description of the personal question (string).
• stateName - The state of the credential (string).
  • Available values:
    • ACTIVE,
    • DISABLED,
    • ARCHIVED
• 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 questions

Create new personal question

POST /{clientExtId}/personal-questions

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

since 2.79

Required permissions

• AccessControl.ClientView,
• AccessControl.PersonalQuestionCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/personal-questions

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "1003",
  "description": "something",
  "stateName": "active",
  "displayName": {
    "DE": "QuestionNew",
    "EN": "QuestionNew",
    "FR": "QuestionNew",
    "IT": "QuestionNew"
  },
  "content": {
    "DE": "QuestionNewContent",
    "EN": "QuestionNewContent",
    "FR": "QuestionNewContent",
    "IT": "QuestionNewContent"
  }
}

Response 201

• Headers: Location: https://your-host/nevisidm/api/core/v1/1000/personal-questions/1003

Get personal questions

GET /{clientExtId}/personal-questions

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

since 2.79

Required permissions

• AccessControl.ClientView,
• AccessControl.PersonalQuestionView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/personal-questions

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    {
      "extId": "102",
      "clientExtId": "1000",
      "created": "2020-08-25T13:03:50Z",
      "lastModified": "2020-08-25T13:03:50Z",
      "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",
      "created": "2020-08-25T13:03:50Z",
      "lastModified": "2020-08-25T13:03:50Z",
      "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": "1598421864000_101",
    "limit": 100
  }
}

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.

since 2.79

Required permissions

• AccessControl.PersonalQuestionView,
• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/personal-questions/2233

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 2233

  ExtID of the personal question.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "extId": "2233",
  "clientExtId": "1000",
  "version": 1,
  "created": "2020-08-25T13:03:50Z",
  "lastModified": "2020-08-25T13:03:50Z",
  "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.

since 2.79

Required permissions

• AccessControl.PersonalQuestionDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/personal-questions/2233

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 2233

  ExtID of the personal question.

Response 204

• 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.

since 2.79

Required permissions

• AccessControl.PersonalQuestionView,
• AccessControl.PersonalQuestionModify,
• AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/personal-questions/2233

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• extId: string (required) Example: 2233

  ExtID of the personal question.

Request

• Headers: Content-Type: application/json
• Body:

{
  "version": 1,
  "description": "new description",
  "stateName": "disabled"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "extId": "2233",
  "clientExtId": "1000",
  "version": 1,
  "created": "2020-08-25T13:03:50Z",
  "lastModified": "2020-08-25T13:03:50Z",
  "description": "new description",
  "stateName": "disabled",
  "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"
  }
}

Recovery Code REST Service

Recovery Code REST Service is used to manage Recovery Code credentials.

Recovery Code get DTO

The Recovery Code credential get DTO has the following parameters:

• extId - The external ID of the credential (string).
• userExtId - The external ID of the user to whom the credential belongs(string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • DISABLED,
    • ARCHIVED
• 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 validity in ISO format (string).
  • to - End date of the profile 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).
• codes
  • code - The recovery code (string).
  • usageDate - If the recovery code was already used, then the date of usage is indicated (string).

Recovery Codes

Get Recovery Codes

GET /{clientExtId}/users/{userExtId}/recovery-codes/

Returns the recovery code credential including all the 16 recovery codes of the user with the given external ID.

since 2.78

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/recovery-codes/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "extId": "4321",
  "userExtId": "1234",
  "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,
  "codes": [
    {
      "code": "5ifJ-ZfvM-GaFD-JmVP"
    },
    {
      "code": "cs5M-T31E-VFwD-Il6m"
    },
    {
      "code": "D304-E0Xs-G35n-hVo3"
    },
    {
      "code": "li7L-Ucdn-HK6Q-gcfC"
    },
    {
      "code": "Mj9y-q3Hj-qcvu-fJvS"
    },
    {
      "code": "MUBo-GHeb-xucy-yiTX"
    },
    {
      "code": "mZDP-WuIq-1DPL-b1zW"
    },
    {
      "code": "OuCp-6nPW-HibO-10AN",
      "usageDate": "2020-07-08T12:52:45Z"
    },
    {
      "code": "pJ2F-vvH6-ZOP3-X4rQ"
    },
    {
      "code": "pZ6e-NAQt-mdRe-NRZ7",
      "usageDate": "2020-07-08T12:52:45Z"
    },
    {
      "code": "QYxk-mWLb-Onn2-eGOb"
    },
    {
      "code": "t4w9-1ASz-BlSS-zdLd"
    },
    {
      "code": "tnWf-BNVU-a9ns-Xe2z"
    },
    {
      "code": "VS9b-XtqQ-MaZj-tiaW"
    },
    {
      "code": "wrXB-qkWa-HgcR-W75H"
    },
    {
      "code": "YEw2-xufp-CuFi-uOOu"
    }
  ]
}

Create Recovery Codes

POST /{clientExtId}/users/{userExtId}/recovery-codes/

Creates a recovery code credential and generates 16 new recovery codes for the user with the given external ID.

If they the user already had a recovery code credential, this call deletes all the recovery codes and generates new ones.

since 2.78

Self-admin

Required permissions

• AccessControl.CredentialCreate,
• AccessControl.CredentialModify

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/recovery-codes/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Update Recovery Codes

PATCH /{clientExtId}/users/{userExtId}/recovery-codes/

Updates the recovery code credential of the user with the given external ID.

since 2.78

Self-admin

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/recovery-codes/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "version": 10,
  "modificationComment": "Inactivated by admin",
  "stateName": "disabled"
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
    "extId": "4321",
    "userExtId":"1234",
    "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,
    "codes": [
        {
            "code": "5ifJ-ZfvM-GaFD-JmVP"
        },
        {
            "code": "cs5M-T31E-VFwD-Il6m"
        },
        {
            "code": "D304-E0Xs-G35n-hVo3"
        },
        {
            "code": "li7L-Ucdn-HK6Q-gcfC"
        },
        {
            "code": "Mj9y-q3Hj-qcvu-fJvS"
        },
        {
            "code": "MUBo-GHeb-xucy-yiTX"
        },
        {
            "code": "mZDP-WuIq-1DPL-b1zW"
        },
        {
            "code": "OuCp-6nPW-HibO-10AN",
            "usageDate": "2020-07-08T12:52:45Z"
        },
        {
            "code": "pJ2F-vvH6-ZOP3-X4rQ"
        },
        {
            "code": "pZ6e-NAQt-mdRe-NRZ7",
            "usageDate": "2020-07-08T12:52:45Z"
        },
        {
            "code": "QYxk-mWLb-Onn2-eGOb"
        },
        {
            "code": "t4w9-1ASz-BlSS-zdLd"
        },
        {
            "code": "tnWf-BNVU-a9ns-Xe2z"
        },
        {
            "code": "VS9b-XtqQ-MaZj-tiaW"
        },
        {
            "code": "wrXB-qkWa-HgcR-W75H"
        },
        {
            "code": "YEw2-xufp-CuFi-uOOu"
        }
    ]
}
_AccessControl.CredentialView_, _AccessControl.CredentialModify_

Delete Recovery Codes

DELETE /{clientExtId}/users/{userExtId}/recovery-codes/

Deletes the recovery code credential including all the 16 recovery codes of the user with the given external ID.

Self-admin

since 2.78

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/recovery-codes/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 204

• Headers: Content-Type: application/json
• Body: _AccessControl.CredentialDelete_

Safeword REST Service

The Safeword REST Service is used to manage the Safeword credentials.

Safeword external IDs are unique per client only, not globally. Therefore, you always have to set the target client.

Safeword create DTO

The Safeword credential create DTO has the following parameters:

Mandatory

• username - The username of the Safeword credential (string).

Optional

• extId - The external ID of the Safeword credential (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED

Safeword get DTO

The safeword credential get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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 validity in ISO format (string).
  • to - End date of the profile 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).

Safeword patch DTO

The Safeword credential patch DTO has the following parameters.

• username - The username of the Safeword credential (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• 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.

since 2.79

Required permissions

• AccessControl.CredentialCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/safeword/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "safewordExtId",
  "username": "username",
  "stateName": "active"
}

Response 201

• Headers: Location: https://your-host/nevisidm/api/core/v1/1000/users/1001/safeword

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.

since 2.79

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/safeword/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json

Response 200

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

Delete safeword credential

DELETE /{clientExtId}/users/{userExtId}/safeword/

Deletes the safeword credential of the user specified with the userExtId

Self-admin

since 2.79

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/safeword/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 204

• Headers: Content-Type: application/json

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.

since 2.79

Required permissions

• AccessControl.CredentialModify,
• AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/safeword/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "username": "safeword-patch-01",
  "stateName": "active",
  "modificationComment": "safeword-patch-01 comment",
  "version": 2
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "extId": "4321",
  "userExtId": "1234",
  "username": "safeword-patch-01",
  "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": "safeword-patch-01 comment",
  "validity": {
    "from": "2017-08-17T00:00:00Z",
    "to": "2027-08-17T00:00:00Z"
  },
  "version": 3
}

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 always have to set the target client.

SecurID create DTO

The SecurID credential create DTO has the following parameters:

Mandatory

• username - The SecurID user name (string).

Optional

• extId - The external ID of the SecurID credential (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED

SecurID patch DTO

The SecurID credential patch DTO has the following parameters:

• username - The username of the SecurID credential (string).
• stateName - The state of the credential (string).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED
• modificationComment - Textual comment regarding the last modification (string).
• version - Version used for optimistic locking (number).

SecurID get DTO

The SecurID credential get DTO has the following parameters:

• created - Creation time of the SecurID (string).
• lastModified - Last modification time of the SecurID (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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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 (string).
• successfulLoginCount - the count of the successful login attempts (number).
• lastFailedLoginDate - the time of the last failed login (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 validity in ISO format (string).
  • to - End date of the profile 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

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "extId": "securIdExtId",
  "username": "securid_username",
  "stateName": "active"
}

Response 201

• Headers: Location: https://your-host/nevisidm/api/core/v1/1000/users/1001/securid

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

Self-admin

Required permissions

• AccessControl.CredentialView

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/securid/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json

Response 200

• 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 active",
      "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

DELETE /{clientExtId}/users/{userExtId}/securid/

Deletes the SecurID credential associated to the user with the given external ID.

Self-admin

since 2.79

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/securid/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 204

• Headers: Content-Type: application/json

Update SecurID Credential

PATCH /{clientExtId}/users/{userExtId}/securid/

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

since 2.77.0

Required permissions

• AccessControl.CredentialModify,
• AccessControl.CredentialView

Example URI

PATCH https://your-host/nevisidm/api/core/v1/1000/users/1234/securid/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
  "username": "securid_username",
  "stateName": "active",
  "modificationComment": "securid-patch-01 comment",
  "version": 1
}

Response 200

• Headers: Content-Type: application/json
• Body:

{
      "created": "2018-08-07T00:00:00Z",
      "lastModified": "2018-08-07T00:00:00Z",
      "version": 2,
      "extId": "39250002",
      "userExtId": "2345",
      "stateName": "active",
      "username": "securid_username",
      "stateChangeReason": "changed-by-admin",
      "stateChangeDetail": "changed to active",
      "lastSuccessfulLoginDate": "2011-11-11T00:00:00Z",
      "successfulLoginCount": 2,
      "lastFailedLoginDate": "2004-04-04T00:00:00Z",
      "failedLoginCount": 4,
      "modificationComment": "securid-patch-01 comment",
      "validity": {
        "from": "2018-08-07T00:00:00Z",
        "to": "2052-06-03T00:00:00Z"
      }
}

URL ticket REST Service

The URL ticket REST Service is used to manage URL tickets.

URL ticket get DTO

The URL ticket get DTO has the following parameters:

• 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).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• 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, for example, 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 validity in ISO format (string).
  • to - End date of the profile 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).
• personifiedLink - The hashed value of the URL ticket (string).

URL ticket create DTO

The URL ticket create DTO has the following parameters:

Optional

• identification - The identification of the URL ticket (string).
• extId - The external ID of the credential (string).
• policyExtId - The external ID of the used policy (string).
• stateName - The state of the credential (string, default:initial).
  • Available values:
    • INITIAL,
    • ACTIVE,
    • TMP_LOCKED,
    • FAIL_LOCKED,
    • RESET_CODE,
    • ADMIN_CHANGED,
    • DISABLED,
    • ARCHIVED
• urlPrefix - The URL prefix which the created link should be printed, it can overwrite policy set URL prefix (string).

URL ticket

Regenerate URL ticket

GET /{clientExtId}/users/{userExtId}/url-ticket/

Regenerates and returns the URL ticket with the given external ID, belonging to the user with the given external ID. (URL Tickets stored hashed so we have to generate new value to return)

since 2.80

Required permissions

• AccessControl.CredentialView,
• AccessControl.CredentialViewPlainValue

When performing a GET request to retrieve a URL ticket the URL prefix of the ticket can be overwritten using request query parameters.

If not indicated policy defined URL prefix is applied if it exists.

Example

https//your-host.com:8080/nevisidm/api/core/v1/100/users/98/url-ticket/?url-prefix=http://test.test.test/?q=

Example URI

GET https://your-host/nevisidm/api/core/v1/1000/users/1234/url-ticket/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "created": "2020-12-16T11:01:22Z",
  "lastModified": "2020-12-16T11:01:22Z",
  "version": 1,
  "extId": "999999263",
  "userExtId": "27000012",
  "policyExtId": "99990016",
  "stateName": "initial",
  "stateChangeReason": "initialized",
  "personifiedLink": "http://test.test.test/?q=hrcg1xbN6LvnmHAfdq55Pqju9rmf58",
  "validity": {
    "from": "2020-12-16T11:01:22Z",
    "to": "2020-12-17T11:01:22Z"
  }
}

Create a URL ticket

POST /{clientExtId}/users/{userExtId}/url-ticket/

Creates a new URL ticket for the user with the given external ID.

since 2.80

Required permissions

• AccessControl.CredentialCreate

Example URI

POST https://your-host/nevisidm/api/core/v1/1000/users/1234/url-ticket/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Request

• Headers: Content-Type: application/json
• Body:

{
 "extId": "4500",
 "policyExtId": "6789",
 "identification": "someIdentification",
 "stateName": "active"
 "url-prefix": "http://test.test.test/?q="
}

Response 201

• Headers: Location: https://your-host/nevisidm/api/core/v1/1000/users/1001/url-ticket

Delete URL Ticket

DELETE /{clientExtId}/users/{userExtId}/url-ticket/

Deletes the URL ticket of the user with the given external ID.

since 2.85

Required permissions

• AccessControl.CredentialDelete

Example URI

DELETE https://your-host/nevisidm/api/core/v1/1000/users/1234/url-ticket/

URI Parameters

• clientExtId: string (required) Example: 1000

  ExtID of the client.

• userExtId: string (required) Example: 1234

  ExtID of the user.

Response 204

• Headers: Content-Type: application/json

System Value REST service

This service provides system values that are used for selections, for example, to select a supported language or to set a country for a new user.

Required permissions

No permissions are required to use this service.

User states

Get user states

GET /system/user-states/

Returns the available user states.

since 2.79

Example URI

GET https://your-host/nevisidm/api/core/v1/system/user-states/

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    "active",
    "disabled",
    "archived"
  ]
}

Languages

Get languages

GET /system/languages/

Returns the available languages.

since 2.79

Example URI

GET https://your-host/nevisidm/api/core/v1/system/languages/

Response 200

• Headers: Content-Type: application/json
• Body:

{
    "items": [
        "de",
        "fr",
        "it",
        "en",
        ...
    ]
}

Countries

Get countries

GET /system/countries/

Returns the available countries.

since 2.79

Example URI

GET https://your-host/nevisidm/api/core/v1/system/countries/

Response 200

• Headers: Content-Type: application/json
• Body:

{
    "items": [
        "af",
        "ax",
        "al",
        "dz",
        ...
    ]
}

Profile states

Get profile states

GET /system/profile-states/

Returns the available profile states.

since 2.79

Example URI

GET https://your-host/nevisidm/api/core/v1/system/profile-states/

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    "active",
    "disabled",
    "archived"
  ]
}

Credential states

Get credential states

GET /system/credential-states/

Returns the available credential states.

since 2.79

Example URI

GET https://your-host/nevisidm/api/core/v1/system/credential-states/

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    "initial",
    "active",
    "tmp-locked",
    "fail-locked",
    "reset-code",
    "admin-changed",
    "disabled",
    "archived"
  ]
}

Credential state change reasons

Get credential state change reasons

GET /system/credential-state-change-reasons/

Returns the available reasons to change a credential state.

since 2.79

Example URI

GET https://your-host/nevisidm/api/core/v1/system/credential-state-change-reasons/

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    "customized-reason-code",
    "initialized",
    "activated",
    "too-many-login-failures",
    "reset-by-admin",
    "changed-by-admin",
    "changed-by-user",
    "logged-in-with-strong-cred",
    "cert-uploaded",
    "policy-check-failed",
    "renewal",
    "reset",
    "cert-revoked",
    "unlock",
    "changed-by-batchjob"
  ]
}

Policy types

Get policy types

GET /system/policy-types/

Returns the available policy types.

Deprecated

LoginPolicy type is deprecated since 2.75.12. Instead, set this parameter in the Client policy.

since 2.79

Example URI

GET https://your-host/nevisidm/api/core/v1/system/policy-types/

Response 200

• Headers: Content-Type: application/json
• Body:

{
  "items": [
    "PwdPolicy",
    "OTPCardPolicy",
    "TicketPolicy",
    "TempStrongPasswordPolicy",
    "CertificatePolicy",
    "GenericCredentialPolicy",
    "TANPolicy",
    "VascoPolicy",
    "PUKPolicy",
    "URLTicketPolicy",
    "DevicePasswordPolicy",
    "MobileSignaturePolicy",
    "SAMLFederationPolicy",
    "SecurityQuestionsPolicy",
    "ContextPasswordPolicy",
    "OpenAuthenticationPolicy",
    "LoginPolicy",
    "ProfilePolicy",
    "ClientPolicy",
    "UnitPolicy"
  ]
}