Crowd Server Developer

Crowd Server Developer

JSON requests and responses

Instead of XML you may provide and accept entities as JSON, a simpler and more concise format.

Comparison of XML and JSON representations

Compare an authentication context, to be POSTed to the '/session' resource, as application/xml:

1
2
3
4
5
6
7
8
9
10
11
<?xml version="1.0" encoding="UTF-8"?>
<authentication-context>
  <username>my_username</username>
  <password>my_password</password>
  <validation-factors>
    <validation-factor>
      <name>remote_address</name>
      <value>127.0.0.1</value>
    </validation-factor>
  </validation-factors>
</authentication-context>

and as application/json:

1
2
3
4
5
6
7
8
9
10
11
12
{
   "username" : "my_username",
   "password" : "my_password",
   "validation-factors" : {
      "validationFactors" : [
         {
            "name" : "remote_address",
            "value" : "127.0.0.1"
         }
      ]
   }
}

HTTP Headers

To make a request with JSON, the appropriate HTTP headers are:

1
2
Content-Type: application/json
Accept: application/json

Command-line example with curl

As an example, the following command attempts to authenticate a user by password with a JSON request:

1
curl -i -u application_name:application_password --data '{"value": "my_password"}' http://localhost:8095/crowd/rest/usermanagement/1/authentication?username=my_username --header 'Content-Type: application/json' --header 'Accept: application/json'

If this is the wrong password then we will get:

1
2
3
4
{
   "reason" : "INVALID_USER_AUTHENTICATION",
   "message" : "Failed to authenticate principal, password was invalid"
}

A correct password gives the user's details:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
   "expand" : "attributes",
   "link" : {
      "rel" : "self",
      "href" : "http://localhost:8095/crowd/rest/usermanagement/1/user?username=my_username"
   },
   "name" : "my_username",
   "first-name" : "My",
   "last-name" : "Username",
   "display-name" : "My Username",
   "email" : "user@example.test",
   "password" : {
      "link" : {
         "rel" : "edit",
         "href" : "http://localhost:8095/crowd/rest/usermanagement/1/user/password?username=my_username"
      }
   },
   "active" : true,
   "attributes" : {
      "link" : {
         "rel" : "self",
         "href" : "http://localhost:8095/crowd/rest/usermanagement/1/user/attribute?username=my_username"
      },
      "attributes" : []
   }
}

Representations for requests

These samples show the JSON representations that the Crowd REST Resources expect to receive.

Creating a user with a password

URI

HTTP Method

/user

POST

1
2
3
4
5
6
7
8
9
10
11
{
   "name" : "my_username",
   "first-name" : "My",
   "last-name" : "Username",
   "display-name" : "My Username",
   "email" : "user@example.test",
   "password" : {
      "value" : "my_password"
   },
   "active" : true
}

With CWD-2923 fixed, you will also be able to set attributes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
   "name" : "my_username",
   "first-name" : "My",
   "last-name" : "Username",
   "display-name" : "My Username",
   "email" : "user@example.test",
   "password" : {
      "value" : "my_password"
   },
   "active" : true,
   "attributes" : {
      "attributes" : [
         {
            "name" : "attr-name",
            "values" : [
               "attr-value"
            ]
         }
      ]
   }
}

Setting a user's password

URI

HTTP Method

/user/password?username=USERNAME

PUT

1
2
3
{
   "value" : "new_password"
}

Adding a user to a group

URI

HTTP Method

/user/group/direct?username=USERNAME

POST

1
2
3
{
   "name" : "groupname"
}

Creating a new group

URI

HTTP Method

/user/group

POST

1
2
3
4
5
6
{
   "name" : "groupname",
   "type" : "GROUP",
   "description" : "Group Description",
   "active" : true
}

Adding a nested group as a direct child of another group

URI

HTTP Method

/group/child-group/direct?groupname=PARENT_GROUP_NAME

POST

1
2
3
{
   "name" : "child-group-name"
}

Authenticating with a password

URI

HTTP Method

/authentication?username=USERNAME

POST

1
2
3
{
   "value" : "my_password"
}

Successful Authentication Response

1
2
3
4
{
   "name" : "my_username",
   ...
}

Unsuccessful Authentication Response

1
2
3
4
{
   "reason" : "INVALID_USER_AUTHENTICATION",
   "message" : "Failed to authenticate principal, password was invalid"
}

Creating a new session token

URI

HTTP Method

/session

POST

1
2
3
4
5
6
7
8
9
10
11
12
{
   "username" : "my_username",
   "password" : "my_password",
   "validation-factors" : {
      "validationFactors" : [
         {
            "name" : "remote_address",
            "value" : "127.0.0.1"
         }
      ]
   }
}

Validating a session

URI

HTTP Method

/session/{token}

POST

1
2
3
4
5
6
7
8
{
   "validationFactors" : [
      {
         "value" : "127.0.0.1",
         "name" : "remote_address"
      }
   ]
}

URI

HTTP Method

/config/cookie

GET

Without an SSO domain

1
2
3
4
{
   "name" : "crowd.token_key",
   "secure" : false
}

With an SSO domain

1
2
3
4
5
{
   "domain" : ".atlassian.com",
   "name" : "crowd.token_key",
   "secure" : false
}

Searching for users and groups

URI

HTTP Method

/search

POST

(For searches, consider if Crowd Query Language and a GET would be more appropriate - see Crowd REST Resources - SearchResource.)

Use a single search restriction

1
2
3
4
5
6
7
8
9
{
  "restriction-type": "property-search-restriction",
  "property": {
    "name": "name",
    "type": "STRING"
  },
  "match-mode": "EXACTLY_MATCHES",
  "value": "admin"
}

Combine multiple search restrictions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "restriction-type": "boolean-search-restriction",
  "boolean-logic": "and",
  "restrictions": [
    {
      "restriction-type": "property-search-restriction",
      "property": {
        "name": "name",
        "type": "STRING"
      },
      "match-mode": "EXACTLY_MATCHES",
      "value": "admin"
    },
    {
      "restriction-type": "property-search-restriction",
      "property": {
        "name": "email",
        "type": "STRING"
      },
      "match-mode": "EXACTLY_MATCHES",
      "value": "admin@example.com"
    }
  ]
}