Manage using API

Prerequisite to test following examples is to have an API key with permissions:

Path Methods ACL
/users/core\.user POST off
/users/core\.user\.token POST off
/users/core\.user-group GET, POST on
/users/core\.user-group/[0-9a-fA-F]{24} GET, PATCH, DELETE on

Example API key is constructed to suit an untrusted client. Following examples shows how untrusted clients can form user groups between themselves. One can manage user groups with a trusted client which is easier to do in the terms of security. ACL for a trusted client does not have to be turned on.

Two users are created to be used while demonstrating user groups. First user creation API request is:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "core.user",
    "attributes": {
      "username": "jane-smith",
      "password": "superBestFriends"
    }
  }
}' \
-X POST https://api.jazer.io/users/core.user

Second user creation API request is:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "core.user",
    "attributes": {
      "username": "alice-smith",
      "password": "makeLoveNotWarcraft"
    }
  }
}' \
-X POST https://api.jazer.io/users/core.user

Token creation (login) is performed for jane-smith with API request:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-H 'Authorization: Basic amFuZS1zbWl0aDpzdXBlckJlc3RGcmllbmRz' \
-X POST https://api.jazer.io/users/core.user.token

Create

Example API request creates a group using the token of a user jane-smith where both users are added to the group:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-H 'Authorization: Token <JANE_SMITH_TOKEN>' \
-d '
{
  "data": {
    "type": "core.user-group",
    "relationships": {
      "users": {
        "data": [
          {
            "type": "core.user",
            "id": "<JANE_SMITH_USER_ID>"
          },
          {
            "type": "core.user",
            "id": "<ALICE_SMITH_USER_ID>"
          }
        ]
      }
    }
  }
}' \
-X POST https://api.jazer.io/users/core.user-group

The response contains a created core.user-group document:

{
  "data": {
    "type": "core.user-group",
    "id": "5a36c528ac61055c6c7c13a6",
    "relationships": {
      "users": {
        "links": {
          "self": "https://api.jazer.io/users/core.user-group/5a36c528ac61055c6c7c13a6/relationships/users",
          "related": "https://api.jazer.io/users/core.user-group/5a36c528ac61055c6c7c13a6/users"
        },
        "data": [
          {
            "type": "core.user",
            "id": "5a36c0e8ac61055c6c7c1364"
          },
          {
            "type": "core.user",
            "id": "5a36c179ac61055c6c7c136c"
          }
        ]
      }
    },
    "links": {
      "self": "https://api.jazer.io/users/core.user-group/5a36c528ac61055c6c7c13a6"
    }
  }
}

Same ACL rules apply as with any other document in the system. Only user jane-smith will receive ACL rights to a created core.user-group document. This means only jane-smith can add/remove users from a group (if the client uses API key which undergoes ACL). User jane-smith can change ACL record of a core.user-group document, i.e. grant permission to the other users to allow them to change users of a group.

Upon group creation, only jane-smith has all rights to manage it. However, every user in the system can use a created group as authentication identity. For example, user alice-smith does not have any rights on the created core.user-group document, but for the documents where she does have rights to change ACL record, she can add the created group.

Read

Fetching created user group by ID can be achieved using following API request:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-H 'Authorization: Token <JANE_SMITH_TOKEN>' \
-X GET https://api.jazer.io/users/core.user-group/<GROUP_ID>

The response contains a core.user-group document with the given ID:

{
  "data": {
    "type": "core.user-group",
    "id": "5a36c528ac61055c6c7c13a6",
    "relationships": {
      "users": {
        "links": {
          "self": "https://api.jazer.io/users/core.user-group/5a36c528ac61055c6c7c13a6/relationships/users",
          "related": "https://api.jazer.io/users/core.user-group/5a36c528ac61055c6c7c13a6/users"
        },
        "data": [
          {
            "type": "core.user",
            "id": "5a36c0e8ac61055c6c7c1364"
          },
          {
            "type": "core.user",
            "id": "5a36c179ac61055c6c7c136c"
          }
        ]
      }
    },
    "links": {
      "self": "https://api.jazer.io/users/core.user-group/5a36c528ac61055c6c7c13a6"
    }
  }
}

Update

Updating created group users to only contain jane-smith can be done using following API request:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-H 'Authorization: Token <JANE_SMITH_TOKEN>' \
-d '
{
  "data": {
    "type": "core.user-group",
    "id": "<GROUP_ID>",
    "relationships": {
      "users": {
        "data": [
          {
            "type": "core.user",
            "id": "<JANE_SMITH_USER_ID>"
          }
        ]
      }
    }
  }
}' \
-X PATCH https://api.jazer.io/users/core.user-group/<GROUP_ID>

Delete

To delete a user group use following API request:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-H 'Authorization: Token <JANE_SMITH_TOKEN>' \
-X DELETE https://api.jazer.io/users/core.user-group/<GROUP_ID>