Mmadu User Service Reference

1. Overview

Mmadu User Service is an independent service for managing users. It exposes the following resources for managing users:

  1. AppDomains - This is a tenant, with its own users, groups, roles and authorities.

  2. AppUsers - Representing users of client applications. Users can have custom properties defined by the domain.

  3. Roles and Authorities - Enforcable user privileges.

  4. Groups - Objects used to further categorize users in a tree hierarchy.

2. Features

Currently, mmadu user service provides the following:

  1. Resource Management - Management of domains, users, roles, authorities and groups

  2. Authentication - Provides an api that clients can use to Authenticate their users.

  3. Password Hashing - Passwords of users are hashed and cannot be decrypted.

3. Default Configuration

3.1. Default Port

Mmadu User Service listens to port 15551 by default and this can be configured using the SERVER_PORT environment variable or the server.port SpringBoot property.

4. Managing Domains

A domain is analogous to a realm. This represents a user pool with its own set of users, groups, roles, and authorities.

A client application references users in one domain. A domain is referenced by a domain id. Applications can share the same user base by using the same domain id.

4.1. Setting Up A Domain

With one API call, you can set up users, roles, authorities and groups needed for your domain. Domain configuration is done with a call to POST /domains.

This api is only used for initial domain setup.

Authority: domain.initialize

4.1.1. Domain Setup Request Fields

Path Type Description

[].id

String

Domain id

[].name

String

Domain Name

[].users

Array

List of predefined users

[].authorities

Array

List of predefined authorities

[].roles

Array

List of predefined roles

[].groups

Array

List of predefined groups (starting with parents)

[].roleAuthorities

Array

List of predefined role authority mappings

[].userAuthorities

Array

List of predefined user authority mappings

[].userRoles

Array

List of predefined user role mappings

[].userGroups

Array

List of predefined user group mappings

4.1.2. Sample Domain Setup Request

POST /domains HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLmRvbWFpbi5pbml0aWFsaXplIiwiZXhwIjoxNTk0NDQ5MzU3LCJpYXQiOjE1OTQ0NDkzNTIsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.jwGZcf3sXjMjBgBew4OA8Mgtk6T-rtcHx3oweOs_RwfDb02SdPsh5zygom910G24UGRoBq8lDH9ppn8J37wArjDsuC8AP0IUNhWSXWHtBwIgOB_4EAgwwJhc5jCScBNWBIhIx6KgtK_fQQhUXFzIwG_V1ppb99jcJKPWuszEpmqccKtN0nn12L2CgSHERIAAnnshfrU21HgmSgPMsveCWgtynl5_ve_jGcSkPuqwefRzL6Og0ud_pF9Lm0qPk9RmkgCBG-eywooFnzpJnH1l7qWx9_yWG6zGMJuiZTlQL4_XhVuDs8zlM3v5W57Hlf8m7TVqj4dAZs5YF-vCA-RU5A
Content-Length: 1361
Host: localhost:8080

[
  {
    "id": "1312",
    "name": "global-config",
    "users": [
      {
        "username": "test",
        "password": "test",
        "externalId": 1111,
        "properties": {
          "country": "nigerian"
        }
      }
    ],
    "authorities": [
      {
        "identifier": "read",
        "name": "Read",
        "description": "Read Things"
      },
      {
        "identifier": "execute",
        "name": "Execute",
        "description": "Execute Things"
      }
    ],
    "roles": [
      {
        "identifier": "admin",
        "name": "Admin",
        "description": "admin"
      }
    ],
    "roleAuthorities": [
      {
        "role": "admin",
        "authority": "execute"
      }
    ],
    "userAuthorities": [
      {
        "user": "test",
        "authority": "read"
      }
    ],
    "userRoles": [
      {
        "user": "test",
        "role": "admin"
      }
    ],
    "groups": [
      {
        "identifier": "workers",
        "name": "Workers",
        "description": "App Workers"
      },
      {
        "identifier": "lawyers",
        "name": "Lawyers",
        "description": "Law people",
        "parent": "workers"
      }
    ],
    "userGroups": [
      {
        "user": "test",
        "group": "lawyers"
      }
    ]
  }
]

4.2. Creating A domain

Instead of creating the entire domain environment at one go, you can opt to create just the domain object.

A POST /appDomains request will create a domain.

Authority: domain.create

4.2.1. Domain Creation Request Body

Path Type Description

name

String

The domain name

id

String

ID of the domain (optional, auto-generated)

4.2.2. Sample Domain Creation Request

POST /appDomains HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzMzEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLmRvbWFpbi5jcmVhdGUiLCJleHAiOjE1OTQ0NDkzMzYsImlhdCI6MTU5NDQ0OTMzMSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.DXGEIFBzFzSeSpqpxME5aEYav39htK02f9-QE94YwDP0HDZdEwivuF97LsCTBlJVIqHS1woji446HiBikhXi1wQGS5cauMk-J41XuqzsifMnCFd3Z17i5oNiUWXhmxRz5qcnuKuNimL4wksLzsX9RkYGX0-y4VMuoTSn9PVqGJkhTIytdKFIts0t7lewk73KUAr8MSnJgnnClwn8M6-_jdpNLUtKhgtdEID32S5uRTyLHtgP2owT_19DG_eI9fwELGHFHqxCtNNhdZIhk96n7BVE7x2BcjzhLFyYhKK-Ob7njbO7gyjyUqEyAtQBESDoAUFB2Z-hJJ-6wjVFrl6aUA
Content-Length: 51
Host: localhost:8080

{
  "id" : "00111111",
  "name" : "new-domain"
}

4.2.3. Domain Creation Response

This API returns a HTTP 201 CREATED response with an empty body.

4.3. Retrieving a Domain

A GET /appDomains/<id> request will get a domain with an ID.

4.3.1. Domain Retrieval Path

Table 1. /appDomains/{domainId}
Parameter Description

domainId

The domain ID

4.3.2. Sample Domain Retrieval Request

GET /appDomains/00111111 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzMzEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMDAxMTExMTEuZG9tYWluLnJlYWQiLCJleHAiOjE1OTQ0NDkzMzYsImlhdCI6MTU5NDQ0OTMzMSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.dRhIhXUgZHQVg4w-zUXsY2iMieV9S6gvaC9zQ9zMolU9OXkCc26NcnUkGuV54SW_38W6HM6vwmcv3uB1s0L8fUNHn714XCUZxqpeIWVQ9XhfoMq8fwmwT2tDPcSAZ3fWzrNVizoCDFvWSaOIZkajiuZOmaKkHODXlmQ4IJxWk4SURz1hobcpnx6bp6ZyY4V7PRt1kNjsjNv4AcHS1CY7qWUgvLjGq8cDjTNrHpy26tl3M-iTk08rLrD-bQIlEESUDwvowMS58wPfsohI5rR8tJO-tJOibpKTGT6OVc9Y8kO3JmfgymkOWFWTz5LYANkG-svZLD51OYo0U5SpGFoSVw
Host: localhost:8080

Authority: domain.read

4.3.3. Domain Retrieval Response Fields

This API returns an AppDomain with these fields:

Path Type Description

name

String

The domain name

_links

map

Domain item resource links

4.3.4. Sample Domain Retrieval Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 223

{
  "name" : "new-domain",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/appDomains/00111111"
    },
    "appDomain" : {
      "href" : "http://localhost:8080/appDomains/00111111"
    }
  }
}

4.4. Retrieving All Domains

A GET /appDomains request will get all domains.

4.4.1. Retrieve All Domains Sample

GET /appDomains HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzMzAsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuZ2xvYmFsLmRvbWFpbi5yZWFkIiwiZXhwIjoxNTk0NDQ5MzM1LCJpYXQiOjE1OTQ0NDkzMzAsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.LFI1ypaIOrnOqk0KQ8Kms6Aj8R2qapghG3K0DUUJv7JopWv4r9Ui0_gPo6Ncc8dKWPXEElia9i1mjjpXemDo5B07LzmuSPQYp8gZvEK2mtQXLOaEvlISEegVNvkueN8hgcEtUJ_di8uYLuDnx02hlPpzlBavFNgnt8nOuVXGIM6Zl1UATRUsNXcSN1xoMGCm6FLuyDognCXyzEeDvia51Il1yekVMDdSstMwabpM_g1Rw88kmfU8Kto1xyFtEZMumjkY8BrxYA2-C22mCLEMtJ0p7XS8a-8wZctG7FfEK5Sgbk1-ltySsKBxE4pDDObMni3hXLJNC4NeF4EIw-tUew
Host: localhost:8080

4.4.2. Retrieve All Domains Response Body Fields

This API returns a list of all domains with these fields:

Authority: domain.read

Path Type Description

_embedded.appDomains.[].name

String

The name of the domain

_embedded.appDomains.[]._links

map

Domain item resource links

_links

map

Resource links

page

map

Page information

4.4.3. Retrieve All Domains Response Sample

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1187

{
  "_embedded" : {
    "appDomains" : [ {
      "name" : "global-config",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/appDomains/0"
        },
        "appDomain" : {
          "href" : "http://localhost:8080/appDomains/0"
        }
      }
    }, {
      "name" : "test",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/appDomains/1"
        },
        "appDomain" : {
          "href" : "http://localhost:8080/appDomains/1"
        }
      }
    }, {
      "name" : "test-domain",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/appDomains/test-app"
        },
        "appDomain" : {
          "href" : "http://localhost:8080/appDomains/test-app"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/appDomains"
    },
    "profile" : {
      "href" : "http://localhost:8080/profile/appDomains"
    },
    "search" : {
      "href" : "http://localhost:8080/appDomains/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 3,
    "totalPages" : 1,
    "number" : 0
  }
}

4.5. Updating A Domain

A PATCH /appDomains/<id> request will update a domain with an ID.

Authority: domain.update

4.5.1. Domain Update Request Path

Table 2. /appDomains/{domainId}
Parameter Description

domainId

The domain ID

4.5.2. Sample Domain Update Request

PATCH /appDomains/00111111 HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzMzEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMDAxMTExMTEuZG9tYWluLnVwZGF0ZSIsImV4cCI6MTU5NDQ0OTMzNiwiaWF0IjoxNTk0NDQ5MzMxLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.fTKDK8v6Sd2S1e6tpxVPoEfg6DYXdKa60GhVEb0dvhqQUjzB_iyhHiEiFUHOO6IXgCqiSA9anFA1TLcBqz8LIDgyTm3rF7OWQBzJFMgGfcV-XtUhMr8mDuHh0w3V4UfuQg45u2XD0DGM06C1pldW6OU26TyM2beBA0fS9beCnNu4gZwF1S3WyfYEAdz8gISviXZFO0B_-eJRm_9CWnjucPIgsz6VAeSNIVJCthXKdX-iY9V3-Lehufme6xzwwRi9tjwd7HVCmM0JmOHw8vtLjbtL6rjc2ceD2pPEhp7U5T0C7jCkHs-iu0hJ2KFDKddTjfYQHgUDYApQtEvUqOvKWQ
Content-Length: 23
Host: localhost:8080

{"name":"changed-name"}

4.5.3. Domain Update Response

This API returns a HTTP 204 NO CONTENT response.

4.5.4. Sample Domain Update Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

4.6. Removing A Domain

A DELETE /appDomains/<id> request will remove a domain with an ID.

Authority: domain.delete

4.6.1. Domain Delete Request Path

Table 3. /appDomains/{domainId}
Parameter Description

domainId

The domain ID

4.6.2. Sample Domain Delete Request

DELETE /appDomains/00111111 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzMzEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEuMDAxMTExMTEuZG9tYWluLmRlbGV0ZSIsImV4cCI6MTU5NDQ0OTMzNiwiaWF0IjoxNTk0NDQ5MzMxLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.Zeq6nUbcZpivvQsjlrUi1nxfTPhJ1WNkqDyBLGlBz6Y2FFKVk2DNr6ZUDWk_GPgKMip-qwEZHuY9pH-MyEEbTVlmMW75Ze1iQfMObekvwc19JHJZpwIqbOXpCgwinXTft2qUWunvTCEqMHhcUg6nLqdcD2enAzs2q87H8rIB5Gpj_tlKbKqeTc1LQ5qhdEWwSBbShxrz49YqIlJ-p0dgv2CIZAj6YfVaJhgQAxk2zxPEkmJgmqJzaw8k8rkxAt-9X_HQyFoe0Ika6QxTuIrK5vNBE_eN6WMtd4_UDgjUcEKNdb7erU2nH8pUMc12Hbt7jptmb2VL3YyL2O2BlBHlXw
Host: localhost:8080

4.6.3. Delete Domain Response

This API returns a HTTP 204 NO CONTENT response.

4.6.4. Sample Delete Domain Response

HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

5. Authentication

Using the rest api, you can authenticate users given a username and password.

A POST /domains/{domainId}/authenticate request authenticates a user on a domain.

Authority: user.authenticate

5.1. Authentication Request

5.1.1. Request Body

Path Type Description

username

String

The user identification

password

String

The user’s password

5.1.2. Authentication Request Path

Table 4. /domains/{domainId}/authenticate
Parameter Description

domainId

The user authentication domain id

5.1.3. Sample Authentication Request

POST /domains/test-app/authenticate HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci5hdXRoZW50aWNhdGUiLCJleHAiOjE1OTQ0NDkzNTYsImlhdCI6MTU5NDQ0OTM1MSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.hHq5sDtcSrP-FX540VcSJ4_rHbVUzCuzi5C0_lx_1uJG2BUIxgdaW1eKeIvxgKH6Qpe-3PJkTE-er2lbdYu8Nl4LEqch3GDASV0MF3zPEwSjBL8YZg2GnWKe_IozbjdpqZcGJ9kguYtbefJV2zEGeQCYENfr6WvwQNfqhv2xFEOEmhzcuBkg-Gp0PZiSAfVrr9jD5HoiUndixi1mjEayKvqSt_ZSo63HpOC3lgCEooCAZeoCvRDEcOzjPhMVoBtH_xJPZVykEPbuIHBMpa_t5-KbFzpyLQwziZfmIoJ0ssjcD2b1FAAH6Tcegpwl6OndLilvly48K3qI3pWqz9gURw
Content-Length: 63
Host: localhost:8080

{
  "username" : "test-user",
  "password" : "my-password"
}

5.2. Authentication Response

This API returns a JSON response with the following fields:

Path Type Description

status

String

The authentication status. One of the following: AUTHENTICATED, USERNAME_INVALID, PASSWORD_INVALID

5.2.1. Sample Authentication Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 26

{"status":"AUTHENTICATED"}

6. Managing Users

The User management endpoints provide APi’s for managing a user.

6.1. Creating A User

A POST /domains/{domainId}/users request will create a user.

Authority: user.create

6.1.1. User Creation Request Body Fields

Path Type Description

username

String

The user’s username (must be unique)

id

String

The user’s id (unique identifier used to reference user in your application)

password

String

The user’s password

6.1.2. User Creation Request Path

Table 5. /domains/{domainId}/users
Parameter Description

domainId

The domain id of the user

6.1.3. Sample User Creation Request

POST /domains/test-app/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzODEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci5jcmVhdGUiLCJleHAiOjE1OTQ0NDkzODYsImlhdCI6MTU5NDQ0OTM4MSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.MwiUdV21AKyTohJDZwqXRdW4gsMY0mokC5m-BjrFkOGU7d6P_PFsBKxC0yqbK7osA0YCQnlfGo9uF6hApr_ynJhrILME7W0CJF2yLsNWk9bWNEwijn-yYBGcNWmOgjcrtHseSR8SXp-q8qTZeu2qqEK8stfky7TjVlVYT-eRm2HvMdif3eyQstyDDQqS4PtQQ0voEzZU5XW-aBZjaoK-E5NZpq4AiasMzaQxRjYxnQeJSln8WUnCXIyPC8xxRcLwY5ZyOu0wdmYh7NDaKdPyUovdHgRFSKniFaRch4gqJ-cqVqoS6oXmBW8QZEGqaR7oG8-6eTBZCYqUGoouBdHqDw
Content-Length: 67
Host: localhost:8080

{"id":"123","username":"user","password":"password","color":"blue"}

As seen in the example, you can also add custom properties like the "color" property.

6.1.4. User Creation Response

This API returns a HTTP 201 CREATED response with an empty body.

6.2. Retrieving A User

A GET /domains/{domainId}/users/{userId} request will get a user with an ID.

Authority: user.read

6.2.1. User Retrieval Request Path

Table 6. /domains/{domainId}/users/{userId}
Parameter Description

userId

The user’s ID

domainId

The domain id of the user

6.2.2. Sample User Retrieval Request

GET /domains/test-app/users/123453432 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzODAsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci5yZWFkIiwiZXhwIjoxNTk0NDQ5Mzg1LCJpYXQiOjE1OTQ0NDkzODAsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.hxyGb4sMcoLgQNMUxBagHHFFvJrOlGGMabaKBEYYcFR0q6NHMQgT5fB-1jAxkv4c01GI46CbwMkbDGNuaRLYee1jRaYpV0aHCOllIsQnYEPg8teqhCDdBdhLEO0tP_KVl_515rJVrOx6uL2GndGWiMx0Cnwb86mGMW7kahXZ3VzYpucKi6SHS1fiRSnGycj4O5wJUVjf07LSs8JWeLt-6AYUjqdcTCDdZ67Tw8aoJJUptOFqmEbtyjmavhQ7IsZMUyo7tOvBsBXl1aqSkd4lOoaiWMuSSLwQ0eW24JRosjZjTbNQVlVdZDQQNiEEPz3D7Fpuo4MG58ntmuCCvAczfw
Host: localhost:8080

6.2.3. User Retrieval Response

This API returns an AppUser with these fields as well as custom fields provided by the client:

Path Type Description

id

String

The user’s id

username

String

Username of the user

password

String

password of the user

roles

string list

List of roles assigned to this user

authorities

string list

List of authorities given to ths user

6.2.4. Sample User Retrieval Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 140

{"id":"123453432","roles":[],"authorities":[],"username":"test-user","password":"my-password","favourite-colour":"blue","country":"Nigeria"}

As you can see, this user has two extra properties: favourite-color and country.

6.2.5. Retrieving All Users In a Domain

A GET /domains/{domainId}/users request will get all users in a domain.

Authority: user.read

6.2.6. Domain Users Retrieval Request Query Params

The request includes page information to request for particular sets in the list.

Parameter Description

page

page number to request

size

maximum number of items in page

6.2.7. Sample Users Retrieval Request

GET /domains/test-app/users?page=0&size=10 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzODEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci5yZWFkIiwiZXhwIjoxNTk0NDQ5Mzg2LCJpYXQiOjE1OTQ0NDkzODEsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.ZYIHiRFGKgk1Ktxq44CrjPhOQlwNL78qFVT0zTAeLY2cjeUOU_R6og931tlXBhIJjRjHPiPcPkLhtz_hWofOlWRL6P8YORvBycgC-TTQy-aw9gneMmi_rtD8v4v6osMvhB3Dx0XeFqjamJTtdLDmvLSngjEsczNtXFHXy5paIPdEjif43TbFX0FUQKAZiOUMcsh74t6lgGbWdhZVZv192n7jgB46UrCLzVNcmcFEibCR3sbkm-b4XTI6T800IraIHYdtSkyXlv69GR8hb7__j4kRMgCoK-jY2EqblpZJk14OOay7kvYEQamP56bZJ-mJzBn2D_G1pl-au3B3CUNzsg
Host: localhost:8080

6.2.8. Users Retrieval Response

This API returns a list of all users with the fields below. The response also has fields that display the page information of result. These fields are shown in the example response and are self explanatory.

Path Type Description

content.[].id

String

The user’s unique identification

content.[].username

String

Username of the user

content.[].password

String

password of the user

content.[].roles

string list

List of roles assigned to this user

content.[].authorities

string list

List of authorities given to ths user

6.2.9. Sample Retrieval Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 606

{"content":[{"id":"123453432","roles":[],"authorities":[],"username":"test-user0","password":"my-password0","country":"Nigeria","favourite-color":"blue"},{"id":"123453432","roles":[],"authorities":[],"username":"test-user1","password":"my-password1","country":"Nigeria","favourite-color":"blue"},{"id":"123453432","roles":[],"authorities":[],"username":"test-user2","password":"my-password2","country":"Nigeria","favourite-color":"blue"}],"totalElements":3,"totalPages":1,"last":true,"number":0,"size":10,"sort":{"sorted":false,"unsorted":true,"empty":true},"numberOfElements":3,"first":true,"empty":false}

6.3. Removing A User with an ID

A DELETE /domains/{domainId}/users/{userId} request will remove a user with an ID.

Authority: user.delete

6.3.1. User Deletion Request Path

Table 7. /domains/{domainId}/users/{userId}
Parameter Description

domainId

The user’s domain ID

userId

The user’s ID

6.3.2. Sample User Deletion Request

DELETE /domains/test-app/users/123453432 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzODAsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci5kZWxldGUiLCJleHAiOjE1OTQ0NDkzODUsImlhdCI6MTU5NDQ0OTM4MCwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.UA-nFoDsrJRdzq3yfU0DrWc7WGr2i4ukIa5WWwScaGvHoG-TNrr58hSwpfmEREBjidtc5K80SJ-9If6gUOXxNKNXubDb_IJyW7hZk-_R2TRq4Z4TWYcGBIZpLUzSZJJfuXA__BsU-LQHSfFEBswbXcODQOeaQN-BegElWNIIFzRk_QXcx7txAihlMyQCP2kjE7sShgH0RwLVJ4KxhErraUotzKi255zXN48FOaxhKJzd9D53ne4IdDUnOW43u-VzJWoWYNK6O2Kg_Q6ciYeFpGtKiD-O6cCcEA3cOjVI14jSSqJoN9PzUYWV4fYF1yn4_OipIt2bmQMfwSQcE6e2qA
Host: localhost:8080

6.3.3. User Deletion Response

This API returns a HTTP 204 NO CONTENT response.

6.3.4. Sample User Deletion Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

6.4. Updating A User with an ID

A PUT /domains/{domainId}/users/{userId} request will update a user with an ID. This will completely overwrite the properties of the existing user. There are no partial updates.

Authority: user.update

6.4.1. User Update Request Path

Table 8. /domains/{domainId}/users/{userId}
Parameter Description

domainId

The user’s domain ID

userId

The user’s ID

6.4.2. Sample User Update Request

PUT /domains/test-app/users/123453432 HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzODEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci51cGRhdGUiLCJleHAiOjE1OTQ0NDkzODYsImlhdCI6MTU5NDQ0OTM4MSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.YbfvnCO6abbBZdMxdypsLct4V76LsuQpjYq-sWwd65KsQdfzeZYqgR0T6w6X0FNaTaJikcHlZIdop6cCMbmhqSJgpzaAQOu6CZ-rZx1sKOUMr6K6pH5cKx2Hd1vyyk27wp_IXK91rLxDLGovFlOkGXdms9qOarNxnhYqT1JtAuZv6zJanLo_RlczscZXaEwmBuo8ZS3uVH6N6bcb5t_KV8zqxfCv_s_DgJ90t8zGIBXCmfuhtPx47TG7tzTR6Ty7vuKNn6koHEEISYpeE-_I_QJwtjSDcpLje93PhouSnAp2aITfKk3pHLiVZSeEslJYCSb9SbLXw5yecdt1P1EN3g
Content-Length: 75
Host: localhost:8080

{
  "username" : "changed-username",
  "password" : "changed-password"
}

6.4.3. User Update Response

This API returns a HTTP 204 NO CONTENT response.

6.4.4. Sample User Update Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

6.5. Loading A User By Username

A GET request will get a user with the specified username and domain id. This will return all roles, authorities and groups associated with that user.

Authority: user.load

6.5.1. User Load Request Path Parameters

Table 9. /domains/{domainId}/users/load
Parameter Description

domainId

The domain id of the user

6.5.2. User Load Request Query Parameters

Parameter Description

username

The username of the user

6.5.3. Sample User Load Request

GET /domains/test-app/users/load?username=test-user HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzODAsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci5sb2FkIiwiZXhwIjoxNTk0NDQ5Mzg1LCJpYXQiOjE1OTQ0NDkzODAsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.CkhpiS9hITEurcDFyxNijreX1yH5c3OCw2cd8EUQMydkj-8fsBk2XfiADDucS_B0zRgQk4g9vSyUzX0jjOeZA47zewWhBnjofeoN56h9PSPK-szn2wdn5-b7glPXyITMPEiuaZSrTYSayA-P9zTQpyr7X1Vf1CRAkWEyjihdKXW8SVBjmfDXqDsprs-9QuVn_I_CkFux_jn4cnIsH8-EzT42hTzycg5yNzmIJFSO-uuYgs6-c4rhM0SpLlsLTZMda0QK1ZtxsudqmGwBd2tGlnkfs5ewdgUYF7JZz8sRxelielstgQ8NFdXABDwTotMJ8p74pTxRMmcLm56BjHeFxw
Host: localhost:8080

6.5.4. User Load Response

This API returns an AppUser with the fields below and other custom fields provided by the domain client.

Path Type Description

id

String

The user’s id

username

String

Username of the user

password

String

password of the user

roles

string list

List of roles assigned to this user

authorities

string list

List of authorities given to ths user

6.5.5. Sample User Load Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 152

{"id":"123453432","roles":[],"authorities":[],"groups":[],"username":"test-user","password":"my-password","favourite-colour":"blue","country":"Nigeria"}

6.6. Querying Users

A GET request can search for users by username, and other custom fields created by the client.

Authority: user.read

Query string can only support custom string, integer and boolean fields currently.
Ensure to put individual criteria in parentheses.

6.6.1. User Query Request Query Parameters

The request includes page information to request for particular sets in the list.

Parameter Description

query

The query search string. Use any of your custom properties for this search including username

page

page number to request

size

maximum number of items in page

6.6.2. Sample User Query Request

GET /domains/test-app/users/search?page=0&size=10&query=%28country+equals+%27Nigeria%27%29+and+%28favourite-color+equals+%27blue%27%29 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzODEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci5yZWFkIiwiZXhwIjoxNTk0NDQ5Mzg2LCJpYXQiOjE1OTQ0NDkzODEsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.ZYIHiRFGKgk1Ktxq44CrjPhOQlwNL78qFVT0zTAeLY2cjeUOU_R6og931tlXBhIJjRjHPiPcPkLhtz_hWofOlWRL6P8YORvBycgC-TTQy-aw9gneMmi_rtD8v4v6osMvhB3Dx0XeFqjamJTtdLDmvLSngjEsczNtXFHXy5paIPdEjif43TbFX0FUQKAZiOUMcsh74t6lgGbWdhZVZv192n7jgB46UrCLzVNcmcFEibCR3sbkm-b4XTI6T800IraIHYdtSkyXlv69GR8hb7__j4kRMgCoK-jY2EqblpZJk14OOay7kvYEQamP56bZJ-mJzBn2D_G1pl-au3B3CUNzsg
Host: localhost:8080

6.6.3. User Query Response

This API returns a list of all users with the fields below. The response also has fields that display the page information of result. These fields are shown in the example response and are self explanatory.

Path Type Description

content.[].id

String

The user’s unique identification

content.[].username

String

Username of the user

content.[].password

String

password of the user

content.[].roles

string list

List of roles assigned to this user

content.[].authorities

string list

List of authorities given to ths user

6.6.4. Sample User Query Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 606

{"content":[{"id":"123453432","roles":[],"authorities":[],"username":"test-user0","password":"my-password0","country":"Nigeria","favourite-color":"blue"},{"id":"123453432","roles":[],"authorities":[],"username":"test-user1","password":"my-password1","country":"Nigeria","favourite-color":"blue"},{"id":"123453432","roles":[],"authorities":[],"username":"test-user2","password":"my-password2","country":"Nigeria","favourite-color":"blue"}],"totalElements":3,"totalPages":1,"last":true,"number":0,"size":10,"sort":{"sorted":false,"unsorted":true,"empty":true},"numberOfElements":3,"first":true,"empty":false}

6.7. Partial User Update

A PATCH /domains/{domainId}/users request can update users partially based on a query criteria

Authority: user.update

Query string can only support custom string, integer and boolean fields currently.
Ensure to put individual criteria in parentheses.

6.7.1. Partial User Update Request Parameter

Table 10. /domains/{domainId}/users
Parameter Description

domainId

The domain id of the user

6.7.2. Partial User Update Request

The PATCH request accepts a query string, and an array of update operations.

Path Type Description

query

String

The query criteria for updating users

updates.[].operation

String

The kind of update operation to make: (SET, INCREMENT, ADD, REMOVE

updates.[].property

String

The property to update

updates.[].value

String

The value used by the update operation

6.7.3. Sample Partial User Update Request

PATCH /domains/test-app/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzODEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAudXNlci51cGRhdGUiLCJleHAiOjE1OTQ0NDkzODYsImlhdCI6MTU5NDQ0OTM4MSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.YbfvnCO6abbBZdMxdypsLct4V76LsuQpjYq-sWwd65KsQdfzeZYqgR0T6w6X0FNaTaJikcHlZIdop6cCMbmhqSJgpzaAQOu6CZ-rZx1sKOUMr6K6pH5cKx2Hd1vyyk27wp_IXK91rLxDLGovFlOkGXdms9qOarNxnhYqT1JtAuZv6zJanLo_RlczscZXaEwmBuo8ZS3uVH6N6bcb5t_KV8zqxfCv_s_DgJ90t8zGIBXCmfuhtPx47TG7tzTR6Ty7vuKNn6koHEEISYpeE-_I_QJwtjSDcpLje93PhouSnAp2aITfKk3pHLiVZSeEslJYCSb9SbLXw5yecdt1P1EN3g
Content-Length: 105
Host: localhost:8080

{"query":"(country equals 'Nigeria')","updates":[{"operation":"SET","property":"color","value":"green"}]}

6.7.4. Partial User Update Response

The API returns 204 No content for a successful update.

6.7.5. Sample Partial User Update Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

7. Managing Groups

Users can be categorized into groups and groups can be a parent or a child of another group. This makes is possible to create nested hierarchies of users.

For instance, to model an office application you can have a root group called Staff and other sub groups like cleaners, receptionists, managers, technicians and so on. Under managers, you can have regional_managers and country_managers.

In the hierarchy above, adding a user to the country_managers group means that the user is also in the managers group and the staff group.

Removal of the user from the country managers group removes the user from all parent groups. You have to explicitly add the user in the staff group if you want the user to remain in that group.

Groups can also be used to implement multi-tenant solutions. Group information is added to the jwt token so that services can know which groups a user belongs.

7.1. Creating A Group

A 'POST /domains/{domainId}/groups' request will create a group.

Authority: group.create

7.1.1. Group Creation Request Body Fields

Path Type Description

identifier

String

The group identifier

name

String

The name of the group

description

String

A brief description of the group

parentGroup

String

The parent group of the group (if a sub group is being created)

7.1.2. Group Creation Request Path

Table 11. /domains/{domainId}/groups
Parameter Description

domainId

The domain id of the user

7.1.3. Sample Group Creation Request

POST /domains/test-app/groups HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuZ3JvdXAuY3JlYXRlIiwiZXhwIjoxNTk0NDQ5MzU2LCJpYXQiOjE1OTQ0NDkzNTEsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.gKUjgEWKymdQExaXqfOJHV8JnRMsNVvNj_Nd4sGfjwxzfCTlQYK-Rs4u8WKhJHm4Z7dcjV5tA5pV0AeIC_3n4mhqrkg7AzJ8BtdDQ1PCoy-wQbd95WoLQh4cgvA34oOJu7AZkAFPiz1NvPaJt3LQuMNs2CLnwfCB5IKW3w5S_V0sJSehckX2cYiukMiqdCwr2gxYDYupIYkZCbtL2glaVvdYveagKcUSbp5bBFdSuOU7tN8JjEX4RGjIpjxy_IRIuS9s_gjeYj5NSREhUaqjJ7ElUjMwpF2mg3rxj__d_3hR8EmGW8_6-BBk-s7eZpkxND37HU1VGze-6eJSStXDrg
Content-Length: 93
Host: localhost:8080

{"identifier":"test","name":"Test Group","description":"A test Group","parentGroup":"sample"}

Here we create a group with identifier test and set the parent to a group with identifier sample. Adding a parent is optional. Create top level groups by setting the parent to null or omitting the property.

7.1.4. Group Creation Response

This API returns a HTTP 201 CREATED response with an empty body.

7.2. Adding User To A Group

You can add user to a group by making a POST call.

Authority: group.add_user

7.2.1. User Group Addition Request Path

Table 12. /domains/{domainId}/groups/{groupIdentifier}/users/{userId}
Parameter Description

domainId

The domain id of the group

groupIdentifier

The group identifier

userId

The id of the user

7.2.2. Sample User Group Addition Request

POST /domains/test-app/groups/sample/users/123453432 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuZ3JvdXAuYWRkX3VzZXIiLCJleHAiOjE1OTQ0NDkzNTYsImlhdCI6MTU5NDQ0OTM1MSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.Jm3Y7SWZyqlVMPYaxe1-RbdYewHXA9kwmglGm67ziR_zen1nyi7WeSQ2626NHY-RKvKyerLzxk9Wky_EkfCkogXNZwo9VFk5wAAViIvPtdY3rr0UI1uth95YCGdi-dazb5NIA_rxJzu7BfYMVvo_JFqopfbnYIUfVK9qqJT5sQVcpLzd869RskDntnCzu8bWBUcdwTDGcjbTROT33jp8NdQ_x8t2DQaqYklkEtk6868mm_spN6RWiYdDcK3NTD2_JZA2sSRW9HiH1zgq7M0uNZX2E6k_nr1rQGh7j3lIkgL3ec_yNlZ0m2lp_yOqDlWyDGGNwhppy4cR6VnktFuVwA
Host: localhost:8080

7.2.3. User Group Addition Response

The api responds with a HTTP 204 No Content response.

7.2.4. Sample Group addition Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

7.2.5. Removing a User From a Group

You remove a user from a group by making a DELETE call below:

Authority: group.remove_user

Table 13. /domains/{domainId}/groups/{groupIdentifier}/users/{userId}
Parameter Description

domainId

The domain id of the group

groupIdentifier

The group identifier

userId

The id of the user

7.2.6. Sample User Group Removal Request

DELETE /domains/test-app/groups/sample/users/123453432 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuZ3JvdXAucmVtb3ZlX3VzZXIiLCJleHAiOjE1OTQ0NDkzNTcsImlhdCI6MTU5NDQ0OTM1MiwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.a_TX5pgNkG17QeZHlmmcC2nfOWFZYlDoVyRhTZDsL_JxghMK284yMf84f70d0kUss7yjc-1kcimc46JDLEobvE3TZPZYKW3E6sOvUBfIsguJg5HFLsut8iDdBmP6yGKunLO9JYob5-ge5VCGPC6njFhTUtN5GvnFGke9WRS3LMLoRKUUV5fvT6bTTa1ODuEewqyWaCXfTFYG6lJ0hx3CnClMacJ7MyyB-_-laebjsdP5CDH1PA3BaBB4QZ1XZ0E9ZjnXRQnUrR-i_GojHVwlhZ7oT2uC_-ke1x_5ua1Y2B-R4x2r5_OIm86vdbYz2J8Ophxm9V-VepZrL7sB6Vbl6g
Host: localhost:8080

7.2.7. User Group Removal Response

The server responds with a HTTP 204 No Content if successful.

7.2.8. Sample User Group Removal Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

7.3. Getting all Users In Groups

A GET request returns all users in a group.

Authority: group.read

7.3.1. User Group Retrieval Request

Table 14. /domains/{domainId}/groups/{groupIdentifier}/users
Parameter Description

domainId

The domain id of the group

groupIdentifier

The group identifier

7.3.2. Sample Group Retrieval Request Body Fields

GET /domains/test-app/groups/sample/users?page=0&size=10 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTEsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuZ3JvdXAucmVhZCIsImV4cCI6MTU5NDQ0OTM1NiwiaWF0IjoxNTk0NDQ5MzUxLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.eF_SRo8lBVAL6HOw65zA84vaU3G-4Azo-58Z5zYvh0hirldvwo0H4d-oVIbhckDdIEvo4fwel-ebtuYaptpXORcXBeNOTe6w6PAAu3x0GnaKFrVQvw6yzvQ3uc354RD_ZAilSVgDFuS4FgR4vDVSkH07DzmbqA4kZ4k0eQ29CocrA8oIUetJwO09JhgNolU5kXGeddlGAjqPEF02xC_GUbmjMACj4wurrPYktUXDeyjknZAqI3Aqhz727pVv2ccW9T7r1UQ6-qphTdY630olyeGyTT-8WzJHAs5P_LJp7pA58ojimUBlGuGUMRDTllRsGq-oU0YNrSg60_53e0wP0A
Host: localhost:8080

7.3.3. Sample Group Retrieval Request Query Parameters

Parameter Description

page

page number to request

size

maximum number of items in page

7.3.4. Group Retrieval Response

The server responds with a HTTP 200 OK with a paginated list of users.

Path Type Description

content.[].id

String

The user’s unique identification

content.[].username

String

Username of the user

content.[].password

String

password of the user

content.[].roles

string list

List of roles assigned to this user

content.[].authorities

string list

List of authorities given to ths user

7.3.5. Sample Group Retrieval Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 606

{"content":[{"id":"123453432","roles":[],"authorities":[],"username":"test-user0","password":"my-password0","country":"Nigeria","favourite-color":"blue"},{"id":"123453432","roles":[],"authorities":[],"username":"test-user1","password":"my-password1","country":"Nigeria","favourite-color":"blue"},{"id":"123453432","roles":[],"authorities":[],"username":"test-user2","password":"my-password2","country":"Nigeria","favourite-color":"blue"}],"totalElements":3,"totalPages":1,"last":true,"number":0,"size":10,"sort":{"sorted":false,"unsorted":true,"empty":true},"numberOfElements":3,"first":true,"empty":false}

8. Managing Roles

Roles are a way to batch authorities. When a role is mapped to some certain privileges/authorities, a user with that role automatically has those privileges.

8.1. Creating A Role

A 'POST /domains/{domainId}/roles' request will create a role. Roles that already exists will be updated. With this api, you can create multiple roles and initialize them with their respective authorities. This is useful for initializing all the roles and authorities an application needs in one step.

Authority: role.create

8.1.1. Role Creation Request Body Fields

Path Type Description

[].identifier

String

The role identifier

[].name

String

The name of the role

[].description

String

A brief description of the role

[].authorities

Array

A list of authority identifiers to be granted to this role

8.1.2. Role Creation Request Path

Table 15. /domains/{domainId}/roles
Parameter Description

domainId

The domain id of the user

8.1.3. Sample Role Creation Request

POST /domains/test-app/roles HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNjksInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAucm9sZS51cGRhdGUiLCJleHAiOjE1OTQ0NDkzNzQsImlhdCI6MTU5NDQ0OTM2OSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.Zprr0ujgnkdC98RDNRn7Qs5eJg5IMeRY9y62ObXYyE2FTGXXLoAH3_a5XYAYrYcc-xIcrvrYT6BLJBfTbMQBft5oF5VexjpoZq9u0z5OQbGuTgZsHRldRzv7I4g-n6rXFqeXGyBmPFPSvOgvA_rDbKlCpEzEI8w9UBUXAtUil6vaCQ6ANFO8VNchn9KNyPpxScMtdPsCDk1yYS6uuybYR63Vrauw-Q0s0hD_O7Ew6VYaHLvStm41n5SoR_9_Dq4dGT1tgJ6u_Y6wOZMznoTd-sDDVu1glr30Wbi14Yo0pGdzVSz92m-arv-N1rF_BeuWBcggARPi8P0iD9GkGNaYFA
Content-Length: 142
Host: localhost:8080

[ {
  "identifier" : "app.view",
  "name" : "View Entities",
  "description" : "View all Entities",
  "authorities" : [ "test-auth" ]
} ]

Here we create a role with identifier test and set the parent to a role with identifier sample. Adding a parent is optional. Create top level roles by setting the parent to null or omitting the property.

8.1.4. Role Creation Response

This API returns a HTTP 201 CREATED response with an empty body.

8.2. Granting a Role to a User

You can grant a role to auser by making a POST call. In the body we specify an array of roles the user is to have.

Authority: role.grant_user

8.2.1. User Role Addition Request Path

Table 16. /domains/{domainId}/roles/users/{userId}/addRoles
Parameter Description

domainId

The domain id of the role

userId

The id of the user

8.2.2. Sample User Role Addition Request

POST /domains/test-app/roles/users/123453432/addRoles HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNjgsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAucm9sZS5ncmFudF91c2VyIiwiZXhwIjoxNTk0NDQ5MzczLCJpYXQiOjE1OTQ0NDkzNjgsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.ZBuBLvnFUN6WvruQT5B2o3gGrqiwx6rkd2W_ioWyqRISDHEYWCGJaLK17LAHnBOvzjHGwkMOz_4qBVziUXUYCIoTOJKuC3QwG_SclElHcXd86OLtiy_K408iWEVRMJ5zyYP3dnCbuzlTUIhCFEQm5mAueUiv-u1urc1KEqqh93mUDe3pJfECtEShbfhX4RxrY-QMk7nYUGBpTP4yi0o52nucoVNQkyNUkcYDYsFRMY-IZ1jOhajH_imP1jS-O_i1XffBLoz9J7sZ7FIuciYX0-Q-Y3slzLbTjFt7kQ7tNInxzSREo501fr70deme0nilxeSv3oTIT9-nROZWlN8qkA
Content-Length: 12
Host: localhost:8080

[ "sample" ]

8.2.3. User Role Addition Response

The api responds with a HTTP 204 No Content response.

8.2.4. Sample Role addition Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

8.2.5. Revoke User Role

You remove a role from a user by making a DELETE call below:

Authority: role.revoke_user

Table 17. /domains/{domainId}/roles/users/{userId}/removeRoles
Parameter Description

domainId

The domain id of the role

userId

The id of the user

8.2.6. Sample User Role Removal Request

POST /domains/test-app/roles/users/123453432/removeRoles HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNjgsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAucm9sZS5yZXZva2VfdXNlciIsImV4cCI6MTU5NDQ0OTM3MywiaWF0IjoxNTk0NDQ5MzY4LCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.kAay5Bivtc7EIdaD2nXbmQN_DYPNj01ZunM8y6tS6N8r3e6oQ4NmBIWinZWFUCMiYNJyIHYesn1ULmBP6Wy9ytxTD5F5pDXKC9QwBZABt6M-6TXta-h5Z7ERotFx4bYBpnGiHYIksowH6oFv4MTqitPpTdNFM6z6NyFsoL48_M8gZ7yK2KTIYAbXnN69Bl1WakksGalszmRZ4-ZjKMrfmYy9NWsuk45NxMvA_S7AyF1W5_ZvNnvg20deW1gzfTd8Ofmstarbjh-j9nU5871d2aPs1FcrxCraIvCfU49IKN7KjipFpW3Rb5QSs152cbwiBXa2Ec1F5rOu5hkCn7xzcA
Content-Length: 12
Host: localhost:8080

[ "sample" ]

8.2.7. User Role Removal Response

The server responds with a HTTP 204 No Content if successful.

8.2.8. Sample User Role Removal Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

8.3. Getting all Roles In a Domain

A GET request returns all roles.

Authority: role.read

8.3.1. All Roles Retrieval Request

Table 18. /domains/{domainId}/roles
Parameter Description

domainId

The domain id of the role

8.3.2. Sample All Roles Retrieval Request Query Parameters

Parameter Description

page

page number to request

size

maximum number of items in page

8.3.3. Sample All Role Retrieval Request

GET /domains/test-app/roles?page=0&size=10 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNjksInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAucm9sZS5yZWFkIiwiZXhwIjoxNTk0NDQ5Mzc0LCJpYXQiOjE1OTQ0NDkzNjksImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.fufXkhspadYoA23uU5ONbiquFHMK2kZyngNgved1b8XYNKXUyQywECBpIpLvx_SmMV_29axEdkn9y9EDoPytAdWJahJilfh1BBeZhkDhq_jsR16xS2mtx755eE6aswluIZ3Ldk8sdxRCv-SS0kN0XP2KqyvQotNGKQKrMF31Jnq9q0S3FU4g672duUcL5TSGXpL4Po1x2uQzIg3fNNjXbFhCM0NtUpD4hGNafQCZOmQzJWtgSAMGP90SOR0hvTsKYmZ3Q461fCXmOmbN7lzu8cnInF2gSQni4-3Fe6333DUORF8Eo6dNLtXNwJUZWcp0nZNRzEOmGc_oYSV8PwuxGA
Host: localhost:8080

8.3.4. All Role Retrieval Response

The server responds with a HTTP 200 OK with a paginated list of roles.

8.3.5. All Role Retrieval Response Fields

Path Type Description

content.[].name

String

The name of the role

content.[].identifier

String

The role identifier

content.[].description

String

A brief description of the role

8.3.6. Sample All Role Retrieval Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 253

{"content":[{"identifier":"sample","name":"Sample Role","description":"Sample Role"}],"totalElements":1,"totalPages":1,"last":true,"number":0,"size":10,"sort":{"sorted":false,"unsorted":true,"empty":true},"numberOfElements":1,"first":true,"empty":false}

8.4. Removing a Role

A DELETE Request will remove a role from the domain.

Authority: role.delete

8.4.1. Delete Role Request Path Parameters

Table 19. /domains/{domainId}/roles/{roleIdentifier}
Parameter Description

domainId

The domain id

roleIdentifier

The role identifier

8.4.2. Sample Delete Role Request

DELETE /domains/test-app/roles/sample HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNjksInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAucm9sZS5kZWxldGUiLCJleHAiOjE1OTQ0NDkzNzQsImlhdCI6MTU5NDQ0OTM2OSwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.F0z5uKK05pmDk5jMw6D0NuBXcXdHcSNOGaUCw9cJ-zA7K4gEpkvKKqZoyanqHqAszqbRHT9yB5emjf8f7IkTZjzHHWoXhbJcy_wNhPvdMOicH4CrOl3NReFkuv7zOb88TiUYXJAI-hxzTw2Ykl5oj6gX632k0I_zcMVPpjVuR4KNJlzGDJ_SC2vWfBc4eU8Hnol6ibsrqs2JSVMzpHpP_gmFF89aWiPddzdEGb0E_znP_dkaK8pP0ars3e17eGigVpTMQBq5pv2Gxhizyer7KMNXKjfd9DXaeO3sSTa-hTWiK8hK94vR_aXxGjDACaDPFmhnJBAC1sKSnq1mP9fF4Q
Host: localhost:8080

8.4.3. Delete Role Response

The server responds with a 204 No Content Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

8.5. Adding Authorities to a Role

You can add new authorities to a role. Make a POST request with an array of roles and their additional authorities.

Authority: role.add_authority

8.5.1. Role Authority Addition Request Path Parameters

Table 20. /domains/{domainId}/roles/authorities/add
Parameter Description

domainId

The domain id of the role

8.5.2. Sample Role Authority Addition Request Body

POST /domains/test-app/roles/authorities/add HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNjgsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAucm9sZS5hZGRfYXV0aG9yaXR5IiwiZXhwIjoxNTk0NDQ5MzczLCJpYXQiOjE1OTQ0NDkzNjgsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.JDnr3LZUniDlq7m9dFG3j5GIQGb63NluCaoEjAuYcpvekDXWQjyn43ODHN-8OlKgFeqsdYocOCNGLt5meYsFl9aoHrzWiu1LI95ppLb2oNys1cVHPU0WDyJwxZrW_St8cxl8mTdW74Tq9dLqP506oHa6MkQgdlmBQl_upOdLvFRN8FvEgjXt_t6Ibz0EjBd5Z4w9VXL9FRLd4tyO7vZw1duj_KYMKGT0Sgdu-QzvKGCxUI6gKP9TQLv4sBXlfbi37nDz0xfmn1WaBgKoGYasoxygg6ypUuy7rjVYODiKW7mF7Jjl_N_flAT1yh98fce3fnGKqDnykubo5ALMDqaAVw
Content-Length: 65
Host: localhost:8080

[ {
  "role" : "sample",
  "authorities" : [ "test-auth" ]
} ]

8.5.3. Role Authority Addition Response

The server responds with a 204 No Content Response.

8.5.4. Sample Role Authority Addition Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

8.6. Removing Authorities from a Role

You can remove authorities from a role. Make a POST request with an array of roles and the authorities to remove.

Authority: role.remove_authority

8.6.1. Role Authority Removal Request Path Parameters

Table 21. /domains/{domainId}/roles/authorities/remove
Parameter Description

domainId

The domain id of the role

8.6.2. Sample Role Authority Removal Request Body

POST /domains/test-app/roles/authorities/remove HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNjksInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAucm9sZS5yZW1vdmVfYXV0aG9yaXR5IiwiZXhwIjoxNTk0NDQ5Mzc0LCJpYXQiOjE1OTQ0NDkzNjksImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.Q-BWFLAPP_Z-zMhjTsAqH-JtepTwbVfs8zGnyb-i7k4roJWXaCxLEY7kpNHS_2_86dhkghU6I9sFkCFdechqhgqZaQdLcULshaATsvcjSX1j1XwIqcJCzQTsrvltzTzspJzR8DhHkrTD_kP7w2VAortB50N-64KxqdT6XYqm3pK5pAAA5csFkl1NGNZNXt5JITQ0lLeICk2QPHbkpH9ezWqY_RFauc6eZiMvxwM4tP0hxte_53DLsOJhdOKz8R_gSHjCcJaJ6r0eRBpBw6dVLjkwYu6uukDLKijVaCKllOy3J2dolfOd72kCD7VDDJaQgjtlUN31J8x4KzDafi6miQ
Content-Length: 65
Host: localhost:8080

[ {
  "role" : "sample",
  "authorities" : [ "test-auth" ]
} ]

8.6.3. Role Authority Removal Response

The server responds with a 204 No Content Response.

8.6.4. Sample Role Authority Removal Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

9. Managing Authorities

Authorities represent privileges granted to the user.

9.1. Creating an Authority

A POST request will create an authority.

Authority: authority.create

9.1.1. Create Authority Request Path

Table 22. /domains/{domainId}/authorities
Parameter Description

domainId

The domain id of the user

9.1.2. Create Authority Request Body Fields

Path Type Description

[].identifier

String

The authority identifier

[].name

String

The name of the authority

[].description

String

A brief description of the authority

9.1.3. Sample Create Authority Request

POST /domains/test-app/authorities HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTMsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuYXV0aG9yaXR5LnVwZGF0ZSIsImV4cCI6MTU5NDQ0OTM1OCwiaWF0IjoxNTk0NDQ5MzUzLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.Uzrd9aPMiTLbAdnidpi8eC_3I7-44JPRCxmuycGIQMN3K335Bo--uS7Df-1zcGezCvwHZ8JH4fs7tL5jv23EZDl6jyWSk7-7dhlDdsBNDQSwpAXgIy-cEbh1MeVoUQJlmiZSMVxfUCs0f5VFHidwaF_lagTk91WkNyMZnB9YW2ZKJwn9g2iLRXMu0eeATVf1iXZd3akz5G1_pgckDUhNMdevoy9fiCW3vLV8yy12arRo_wC6rJjuzWrCd0JYuRNJpOCvpCANiqFVlCTrXqWAHLXjB5VoAlbXGC9VDnMMMM4XQXSsvnuc_oFhZFq5wUzt-R2REl5-OXJZIZhTS5scDA
Content-Length: 116
Host: localhost:8080

[ {
  "identifier" : "app.view.authority",
  "name" : "View Entities",
  "description" : "View all Entities"
} ]

9.1.4. Create Authority Response

The server responds with a HTTP 201 Created response.

9.1.5. Sample Create Authority Response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

9.2. Get All Authorities in a Domain

A GET request will get all authorities in a domain.

Authority: authority.read

9.2.1. All Authorities Retrieval Request

Table 23. /domains/{domainId}/authorities
Parameter Description

domainId

The domain id of the authority

9.2.2. Sample All Authorities Retrieval Request Query Parameters

Parameter Description

page

page number to request

size

maximum number of items in page

9.2.3. Sample All Authorities Retrieval Request

GET /domains/test-app/authorities?page=0&size=10 HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuYXV0aG9yaXR5LnJlYWQiLCJleHAiOjE1OTQ0NDkzNTcsImlhdCI6MTU5NDQ0OTM1MiwianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.TLxPQVxSgy_5D0m6yXP39pGHbygy6ZW5Yqv5tb5ypTQyj1Q0RWrNXPRUg6WVQC7f6XSz-pWs9I3Nm-tfukoijIXub2EcNb47SB_98S3koD6bILzug7sxJc4W40ovU9krd7Imk8vhTI1d-6LjKX05fsBTnfuKyxuwXXSehqYp7Ux6UyokvgOeqCnoerfcMRTO2gkFHZVCnIuWYIDd34h3fNVQHAsBbugk6UDTPT1ZiCoWClT_GqalNukf_iSNWAh2dfyELZJYQPFaIX-IZrd0FkjBl-GkV04Mgj2qPhNvvamuUqq-6DUkxqX95xdSLYHQiM7NQFbvnEIuRT0DNNEM2w
Host: localhost:8080

9.2.4. All Role Authorities Response

The server responds with a HTTP 200 OK with a paginated list of authorities.

9.2.5. All Authorities Retrieval Response Fields

Path Type Description

content.[].name

String

The name of the authority

content.[].identifier

String

The authority identifier

content.[].description

String

A brief description of the authority

9.2.6. Sample All Authorities Retrieval Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 263

{"content":[{"identifier":"sample","name":"Sample Authority","description":"Sample Authority"}],"totalElements":1,"totalPages":1,"last":true,"number":0,"size":10,"sort":{"sorted":false,"unsorted":true,"empty":true},"numberOfElements":1,"first":true,"empty":false}

9.3. Removing an Authority

Authority: authority.delete

A DELETE Request will remove an authority from the domain.

9.3.1. Delete Authority Request Path Parameters

Table 24. /domains/{domainId}/authorities/{authorityIdentifier}
Parameter Description

domainId

The domain id

authorityIdentifier

The role identifier

9.3.2. Sample Delete Authority Request

DELETE /domains/test-app/authorities/sample HTTP/1.1
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTIsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuYXV0aG9yaXR5LmRlbGV0ZSIsImV4cCI6MTU5NDQ0OTM1NywiaWF0IjoxNTk0NDQ5MzUyLCJqdGkiOiJmNWJmNzVhNi0wNGEwLTQyZjctYTFlMC01ODNlMjljZGU4NmMifQ.VoyrgF69C0LpypzsiZRPMMR9ZmG3LLgtoFAmr_EUpJMcJ2YiRBHjAH8PXXCTncdGSzoO1NwbdvIaRycjtmm3cvqsRPZ1gDJLXVO7UlZTRR1ora84RtCRJGrWXqkZNcqhE8MrcbwDA2QRTTxP9JQF7Foz7ehhe0bk0h902VECPvWxoRGjLA0xY4-5HAjDMTSI9QKfunBYZWwvn-TuRVp8U7FRnkL2MEmyBowpsbXjgf9Qshu3zWxnqGxBUIfKMJBuDtX8-bQ-V3O1gRLLxRZKYYmh3Ns7XDrav3OH4un24j6uaeIADRH-3CcvZyDka-QP-s1QL66CF-7sjscUSEgRpg
Host: localhost:8080

9.3.3. Delete Authority Response

The server responds with a 204 No Content Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

9.4. Granting an Authority to a User

A user can be granted an authority without being attached to a role. Make a POST request to add an authority to a user.

Authority: authority.grant_user

9.4.1. User Authority Addition Request Path Parameters

Table 25. /domains/{domainId}/authorities/users/{userId}/addAuthorities
Parameter Description

domainId

The domain id of the authority

userId

The id of the user

9.4.2. Sample User Authority Addition Request Body

POST /domains/test-app/authorities/users/123453432/addAuthorities HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTMsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuYXV0aG9yaXR5LmdyYW50X3VzZXIiLCJleHAiOjE1OTQ0NDkzNTgsImlhdCI6MTU5NDQ0OTM1MywianRpIjoiZjViZjc1YTYtMDRhMC00MmY3LWExZTAtNTgzZTI5Y2RlODZjIn0.hC8TPhv1S-OwqyVHo3LEY7frF1SLmVkON4ue0shVTGwJ13UvI2ggXayPiBQnFssyMb-VPKuNomAOs9MpBtyFuNiJ1VMRMlBTcWirFDczOoU5sd9fxgPNJ_RDglAIB1bdT7VuX5ayKK8tzNeNO0D8CoIWb8BaMX9oaDItOY5jM7TGvC6R_J4APceIDUsQWaGOoO5R5XqdC2w5OkBTkPM4SpzQ-xs2aapNBAn3kYL9oImf2z7m8lpq7I_0rwDRaC_1HjcHOYJt0-uWArMBPvku2WTaY445qZYg703wGVZsBHj8bjHEDNPFi74sNhp5T_JL6LgEi-f9cJr16Wy-7WV8FQ
Content-Length: 12
Host: localhost:8080

[ "sample" ]

9.4.3. User Authority Addition Response

The server responds with a 204 No Content Response.

9.4.4. Sample User Authority Addition Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

9.5. Revoking User Authorities

You can revoke authorities for a user. Make a POST request with the authority identifier and the user id.

Authority: authority.revoke_user

9.5.1. User Authority Removal Request Path Parameters

Table 26. /domains/{domainId}/authorities/users/{userId}/removeAuthorities
Parameter Description

domainId

The domain id of the authority

userId

The id of the user

9.5.2. Sample User Authority Removal Request Body

POST /domains/test-app/authorities/users/123453432/removeAuthorities HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJraWQiOiIxMjMiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1ZWUzNzhhZDQ3NDg5MTI5Y2M0OWIzYjAiLCJyb2xlcyI6W10sImlzcyI6Im1tYWR1LmNvbSIsImdyb3VwcyI6W10sImF1dGhvcml0aWVzIjpbXSwiY2xpZW50X2lkIjoiMjJlNjViNzItOTIzNC00MjgxLTlkNzMtMzIzMDA4OWQ0OWE3IiwiZG9tYWluX2lkIjoiMCIsImF1ZCI6InRlc3QiLCJuYmYiOjE1OTQ0NDkzNTMsInVzZXJfaWQiOiIxMTExMTExMTEiLCJzY29wZSI6ImEudGVzdC1hcHAuYXV0aG9yaXR5LnJldm9rZV91c2VyIiwiZXhwIjoxNTk0NDQ5MzU4LCJpYXQiOjE1OTQ0NDkzNTMsImp0aSI6ImY1YmY3NWE2LTA0YTAtNDJmNy1hMWUwLTU4M2UyOWNkZTg2YyJ9.XeKU4cqk5mNApx_NRRNZgDx3QPrrVKCtQJhoPn9jLgTiABWrV_l1blloEXVRPtay2XMRzmzPg9tlJDpJvIYB4RoBShD7yz5DevCzii3WdacCVa1S2uW-xSM9OLuTaXQx_l0RkuY_jshTn42tmzMJaNEa7PnrdJCwqwVFjeQEeUiM5fOITWAv2AYL96HaZLqVN5SFxcaoVYCrJItEBOUEHqm6y4-1g4EPXQrUAH70gP1HsUz5j2KSzZwZhdIDxElyCyb5pmHh9T-Dk-W56JcGEMN7Y6BJeFUzASkZvqGQHp0Is4j8Em7DSkmazgR_oUaIW6YmonMR7lh4lagJ7EAKsQ
Content-Length: 12
Host: localhost:8080

[ "sample" ]

9.5.3. User Authority Removal Response

The server responds with a 204 No Content Response.

9.5.4. Sample User Authority Removal Response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY