devel:api:identities.md

# Identity REST endpoint This is a basic endpoint that allows identity management in CzechIdM.

REST endpoint /api/v1/identities
Identities supported extended attributes (EAV model)

# Supports

Basic CRUD operations (Creating, Reading, Updating, Deleting) and searching.
Returns given identity to granted authorities (/authorities).
Returns the currently assigned identity role (/roles). Specifically, it returns the identity / roles bindings (IdmIdentityRoleDto).
Returns the identity of the main position in the organization (/work-position). Returned position contains all work position's parents in the tree structure and contract's working position as path.
This endpoint also allows you to manage extended identity attributes (EAV).

If you want to use the REST API, you must be logged in. The easiest way is to use Basic authentication directly in request "- u admin: admin".

# API TODO: Swagger

# Examples

## Creating new identity You can use the POST method to create a new identity. Below is an example of identity creation new_identity where the query body contains only "user name, last name, first name and email". In response is returned whole new created identity (with all audit fields and generated ID).

### Request: ``` curl -i -X POST -H "Content-Type:application/json" -u admin:admin http://localhost:8080/idm-backend/api/v1/identities/ -d '{"username": "john_doe", "firstName": "John", "lastName": "Doe", "email": "john.doe@czechidm.eu"}' ```

### Response:

{
   "id": "22246775-19be-4088-ab34-cc67a322f731",
   "created": "2017-06-13T09:03:30.127Z",
   "modified": null,
   "creator": "admin",
   "creatorId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
   "modifier": null,
   "modifierId": null,
   "originalCreator": "admin",
   "originalCreatorId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
   "originalModifier": null,
   "originalModifierId": null,
   "username": "new_identity",
   "firstName": "New",
   "lastName": "Identity",
   "email": "new.identity@czechidm.eu",
   "phone": null,
   "titleBefore": null,
   "titleAfter": null,
   "description": null,
   "disabled": false,
   "_trimmed": false,
   "_embedded": {},
   "_links": {"self": {"href": "http://localhost:8080/idm-backend/api/v1/identities/22246775-19be-4088-ab34-cc67a322f731"}}
}

## Getting authorities for identity With uses this endpoint, you can get list of authorities for the identity. In this example for john doe identity. Authority defines what the identity potentially can do. For example, if the IDENTITY_READ authority is returned, it means that the user will see tab Users in the GUI. However, the authorities do not guarantee that the user will see other users as such. This is the task of permissions evaluators.

Edit add tag

### Request: ``` curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/john_doe/authorities' ```

### Response:

[
  {
    "authority" : "CONTRACTGUARANTEE_AUTOCOMPLETE"
  }, {
    "authority" : "CONTRACTGUARANTEE_PASSWORDCHANGE"
  }, {
    "authority" : "CONTRACTGUARANTEE_READ"
  }, {
    "authority" : "IDENTITYCONTRACT_AUTOCOMPLETE"
  }, {
    "authority" : "IDENTITYCONTRACT_PASSWORDCHANGE"
  }, {
    "authority" : "IDENTITYCONTRACT_READ"
  }, {
    "authority" : "IDENTITYROLE_AUTOCOMPLETE"
  }, {
    "authority" : "IDENTITYROLE_PASSWORDCHANGE"
  }, {
    "authority" : "IDENTITYROLE_READ"
  }, {
    "authority" : "IDENTITY_AUTOCOMPLETE"
  }, {
    "authority" : "IDENTITY_PASSWORDCHANGE"
  }, {
    "authority" : "IDENTITY_READ"
  }, {
    "authority" : "ROLE_AUTOCOMPLETE"
  } 
]

## Getting assigned roles for identity With uses this endpoint, you can get list of assigned roles for the identity. In this example for admin identity. For example, a role can assign permissions or accounts on end systems.

List of returned assigned roles not support pagination. Everytime returning all.

### Request: ``` curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/admin/roles'

```

### Response:

{
  "_embedded" : {
    "identityRoles" : [ {
      "id" : "4f2b06cd-5abd-4426-ab52-278741ec8389",
      "created" : "2017-06-12T10:48:42.157Z",
      "modified" : null,
      "creator" : "[SYSTEM]",
      "creatorId" : null,
      "modifier" : null,
      "modifierId" : null,
      "originalCreator" : "[SYSTEM]",
      "originalCreatorId" : null,
      "originalModifier" : null,
      "originalModifierId" : null,
      "identityContract" : "bf843f35-5d31-48e3-9d4d-a224b1ded9de",
      "role" : "2e8d493a-8368-4417-af88-08ad682a2ca1",
      "validFrom" : null,
      "validTill" : null,
      "automaticRole" : false,
      "roleTreeNode" : null,
      "valid" : true,
      "_trimmed" : true,
      "_embedded" : {!Shortened-for-clarity!}
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/idm-backend/api/v1/identities/admin/roles"
    }
  },
  "page" : {
    "size" : 0,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

## Reading identities For get identities without filter, you can use the simple GET request show below. The number of identities returned is limited to 10 . You must use pagination to return more results.

### Request: ``` curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/'

``` ### Response:

{
   "_embedded": {"identities":    [
            {
         "id": "7660871b-8b95-4676-87ba-742ffb5ee881",
         "created": "2017-06-12T10:48:46.998Z",
         "modified": "2017-06-12T10:50:44.096Z",
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": "admin",
         "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": "admin",
         "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "username": "john_doe",
         "firstName": "John",
         "lastName": "Doe",
         "email": "john.doe@czechidm.eu",
         "phone": null,
         "titleBefore": null,
         "titleAfter": null,
         "description": null,
         "disabled": false,
         "_trimmed": true,
         "_embedded": {}
      },
            {
         "id": "5144d990-3d99-4d2e-8c5e-5335f0c3e67e",
         "created": "2017-06-12T10:48:46.450Z",
         "modified": "2017-06-12T10:52:25.242Z",
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": "admin",
         "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": "admin",
         "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "username": "james_smith",
         "firstName": " James",
         "lastName": "Smith",
         "email": "james.smith@czechidm.eu",
         "phone": null,
         "titleBefore": null,
         "titleAfter": null,
         "description": null,
         "disabled": false,
         "_trimmed": true,
         "_embedded": {}
      },
            {
         "id": "a42b0b2a-c4da-4b2d-b4c3-0d82d529e81c",
         "created": "2017-06-12T10:48:45.317Z",
         "modified": "2017-06-12T10:54:54.455Z",
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": "admin",
         "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": "admin",
         "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "username": "richard_miles",
         "firstName": "Richard",
         "lastName": "Miles",
         "email": "richard.miles@czechidm.eu",
         "phone": null,
         "titleBefore": null,
         "titleAfter": null,
         "description": null,
         "disabled": false,
         "_trimmed": true,
         "_embedded": {}
      },
            {
         "id": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "created": "2017-06-12T10:48:41.397Z",
         "modified": "2017-06-12T10:55:51.328Z",
         "creator": "[SYSTEM]",
         "creatorId": null,
         "modifier": "admin",
         "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "originalCreator": "[SYSTEM]",
         "originalCreatorId": null,
         "originalModifier": "admin",
         "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
         "username": "admin",
         "firstName": "Super",
         "lastName": "Admin",
         "email": "admin@czechidm.eu",
         "phone": null,
         "titleBefore": null,
         "titleAfter": null,
         "description": null,
         "disabled": false,
         "_trimmed": true,
         "_embedded": {}
      }
   ]},
   "_links": {"self": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?pageu=0&sizeu=3"}},
   "page":    {
      "size": 10,
      "totalElements": 4,
      "totalPages": 1,
      "number": 0
   }
}

## Reading identities with uses pagination Below is a example of how to get identity using pagination. We specify page of results by page parameter. The size parameter defines the number of records on the page. In this case, the first page will be returned, containing only one identity.

### Request: ``` curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/?page=0&size=1'

``` ### Response:

{
   "_embedded": {"identities": [   {
      "id": "7660871b-8b95-4676-87ba-742ffb5ee881",
      "created": "2017-06-12T10:48:46.998Z",
      "modified": "2017-06-12T10:50:44.096Z",
      "creator": "[SYSTEM]",
      "creatorId": null,
      "modifier": "admin",
      "modifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
      "originalCreator": "[SYSTEM]",
      "originalCreatorId": null,
      "originalModifier": "admin",
      "originalModifierId": "d0c47adb-4cbd-4551-bb20-87567ff7892d",
      "username": "john_doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@czechidm.eu",
      "phone": null,
      "titleBefore": null,
      "titleAfter": null,
      "description": null,
      "disabled": false,
      "_trimmed": true,
      "_embedded": {}
   }]},
   "_links":    {
      "first": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?page=0&size=1"},
      "self": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?page=0&size=1"},
      "next": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?page=1&size=1"},
      "last": {"href": "http://localhost:8080/idm-backend/api/v1/identities/?page=3&size=1"}
   },
   "page":    {
      "size": 1,
      "totalElements": 4,
      "totalPages": 4,
      "number": 0
   }
}

## Get the main identity position in organization Returns the identity of the main position in the organization (/work-position). Returned position contains all work position's parents in the tree structure and contract's working position as path.

### Request: ``` curl -u admin:admin 'http://localhost:8080/idm-backend/api/v1/identities/admin/work-position'

```

### Response:

{
  "id" : "b34e015f-0a27-45f2-b333-c01478d22f37",
  "created" : "2017-06-13T10:54:18.439Z",
  "modified" : "2017-06-13T10:54:29.956Z",
  "creator" : "admin",
  "creatorId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
  "modifier" : "admin",
  "modifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
  "originalCreator" : "admin",
  "originalCreatorId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
  "originalModifier" : "admin",
  "originalModifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
  "identity" : {
    "id" : "7660871b-8b95-4676-87ba-742ffb5ee881",
    "created" : "2017-06-12T10:48:46.998Z",
    "modified" : "2017-06-12T10:50:44.096Z",
    "creator" : "[SYSTEM]",
    "creatorId" : null,
    "modifier" : "admin",
    "modifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "originalCreator" : "[SYSTEM]",
    "originalCreatorId" : null,
    "originalModifier" : "admin",
    "originalModifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "username" : "john_doe",
    "firstName" : "John",
    "lastName" : "Doe",
    "email" : "john.doe@czechidm.eu",
    "phone" : null,
    "titleBefore" : null,
    "titleAfter" : null,
    "description" : null,
    "disabled" : false,
    "_trimmed" : false,
    "_embedded" : { }
  },
  "contract" : {
    "id" : "b34e015f-0a27-45f2-b333-c01478d22f37",
    "created" : "2017-06-13T10:54:18.439Z",
    "modified" : "2017-06-13T10:54:29.956Z",
    "creator" : "admin",
    "creatorId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "modifier" : "admin",
    "modifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "originalCreator" : "admin",
    "originalCreatorId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "originalModifier" : "admin",
    "originalModifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
    "identity" : "7660871b-8b95-4676-87ba-742ffb5ee881",
    "validFrom" : null,
    "validTill" : null,
    "guarantee" : null,
    "position" : "Director",
    "externe" : false,
    "disabled" : false,
    "main" : true,
    "workPosition" : "e8a69620-be42-433b-ad98-1b95d448a6ba",
    "description" : null,
    "valid" : true,
    "_trimmed" : false,
    "_embedded" : {
      "workPosition" : {
        "id" : "e8a69620-be42-433b-ad98-1b95d448a6ba",
        "created" : "2017-06-12T10:48:47.492Z",
        "modified" : null,
        "creator" : "[SYSTEM]",
        "creatorId" : null,
        "modifier" : null,
        "modifierId" : null,
        "originalCreator" : "[SYSTEM]",
        "originalCreatorId" : null,
        "originalModifier" : null,
        "originalModifierId" : null,
        "code" : "one",
        "name" : "Organization One",
        "parent" : "59f10d91-259e-4fad-8820-39b1607665c8",
        "treeType" : "9920488b-984a-40d0-8af8-108332cc25ab",
        "disabled" : false,
        "_trimmed" : true,
        "_embedded" : {
          "parent" : {
            "id" : "59f10d91-259e-4fad-8820-39b1607665c8",
            "created" : "2017-06-12T10:48:42.706Z",
            "modified" : null,
            "creator" : "[SYSTEM]",
            "creatorId" : null,
            "modifier" : null,
            "modifierId" : null,
            "originalCreator" : "[SYSTEM]",
            "originalCreatorId" : null,
            "originalModifier" : null,
            "originalModifierId" : null,
            "code" : "root",
            "name" : "Root organization",
            "parent" : null,
            "treeType" : "9920488b-984a-40d0-8af8-108332cc25ab",
            "disabled" : false,
            "_trimmed" : true,
            "_embedded" : {
              "treeType" : {
                "id" : "9920488b-984a-40d0-8af8-108332cc25ab",
                "created" : "2017-06-12T10:48:42.587Z",
                "modified" : null,
                "creator" : "[SYSTEM]",
                "creatorId" : null,
                "modifier" : null,
                "modifierId" : null,
                "originalCreator" : "[SYSTEM]",
                "originalCreatorId" : null,
                "originalModifier" : null,
                "originalModifierId" : null,
                "code" : "ORGANIZATIONS",
                "name" : "Organization structure",
                "defaultTreeType" : true,
                "defaultTreeNode" : null,
                "_trimmed" : true,
                "_embedded" : { }
              }
            }
          },
          "treeType" : {
            "id" : "9920488b-984a-40d0-8af8-108332cc25ab",
            "created" : "2017-06-12T10:48:42.587Z",
            "modified" : null,
            "creator" : "[SYSTEM]",
            "creatorId" : null,
            "modifier" : null,
            "modifierId" : null,
            "originalCreator" : "[SYSTEM]",
            "originalCreatorId" : null,
            "originalModifier" : null,
            "originalModifierId" : null,
            "code" : "ORGANIZATIONS",
            "name" : "Organization structure",
            "defaultTreeType" : true,
            "defaultTreeNode" : null,
            "_trimmed" : true,
            "_embedded" : { }
          }
        }
      },
      "identity" : {
        "id" : "7660871b-8b95-4676-87ba-742ffb5ee881",
        "created" : "2017-06-12T10:48:46.998Z",
        "modified" : "2017-06-12T10:50:44.096Z",
        "creator" : "[SYSTEM]",
        "creatorId" : null,
        "modifier" : "admin",
        "modifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
        "originalCreator" : "[SYSTEM]",
        "originalCreatorId" : null,
        "originalModifier" : "admin",
        "originalModifierId" : "d0c47adb-4cbd-4551-bb20-87567ff7892d",
        "username" : "john_doe",
        "firstName" : "John",
        "lastName" : "Doe",
        "email" : "john.doe@czechidm.eu",
        "phone" : null,
        "titleBefore" : null,
        "titleAfter" : null,
        "description" : null,
        "disabled" : false,
        "_trimmed" : true,
        "_embedded" : { }
      }
    }
  },
  "path" : [ {
    "id" : "59f10d91-259e-4fad-8820-39b1607665c8",
    "created" : "2017-06-12T10:48:42.706Z",
    "modified" : null,
    "creator" : "[SYSTEM]",
    "creatorId" : null,
    "originalCreator" : "[SYSTEM]",
    "originalCreatorId" : null,
    "modifier" : null,
    "modifierId" : null,
    "originalModifier" : null,
    "originalModifierId" : null,
    "code" : "root",
    "name" : "Root organization",
    "treeType" : null,
    "disabled" : false,
    "externalId" : null,
    "childrenCount" : 2,
    "parent" : null
  }, {
    "id" : "e8a69620-be42-433b-ad98-1b95d448a6ba",
    "created" : "2017-06-12T10:48:47.492Z",
    "modified" : null,
    "creator" : "[SYSTEM]",
    "creatorId" : null,
    "originalCreator" : "[SYSTEM]",
    "originalCreatorId" : null,
    "modifier" : null,
    "modifierId" : null,
    "originalModifier" : null,
    "originalModifierId" : null,
    "code" : "one",
    "name" : "Organization One",
    "treeType" : null,
    "disabled" : false,
    "externalId" : null,
    "childrenCount" : 0,
    "parent" : null
  } ],
  "_trimmed" : false,
  "_embedded" : { }
}