Single Account¶

A single entrecode Account.

The JSON Schema is https://schema.entrecode.de/schema-acc/account.

Properties¶

Property	Type	Format	Description	Writable
accountID	String	Version 4 UUID (RFC 4122)	The unique identifier for an Account	No. Gets generated on creation.
created	String	ISO-8601 formatted UTC Date String (YYYY-MM-DDTHH:mm:ss.sssZ, RFC 3339)	Timestamp of the creation of the Account	No. Gets written on creation.
email	String	valid eMail Address	The primary eMail address of the account	Yes
language	String	Shortened RFC5646 Syntax (`en`, `de`, …)	The primary UI language for this account	Yes
state	String	`active`, `inactive`, `blocked`, `deleted`	The account state	Yes
hasPassword	Boolean		Optional. Indicates if the user has a password set.	No
hasPendingEmail	Boolean		Optional. Indicates if the user has a pending email change	No
openID	Array	OAuth Accounts	of linked OAuth / Open ID Connect accounts. Each Array item is an object including the fields `sub` (subject), `iss` (issuer), `pending` (true/false), `email` and `name` (as given from the OAuth issuer)	Yes
permissions	Array[String]	Shiro permission string	Permissions that are directly assigned to this account (excluding group permissions).	Yes
groups	Array	objects containing `name`, `groupID` and a `permissions` array	Groups this account is assigned to, including group permissions (permissions inherited by group membership). Groups are not linked to the group resource because other members may not be disclosed.	No. Edit the group resource to change memberships.

Note to deprecated isPrincess field: This field is not included anymore. Just check for membership in the Princesses group.

Relations¶

Relation Name	Target Resource	Description	Possible Methods
self	Account	The resource itself	GET, PUT
collection	Account List	List of all available Accounts	GET
ec:account/tokens	Token List	Collection of access tokens for this account	GET

List¶

The Account List Resource is a Generic List Resource with embedded Account Resources.

Possible Actions¶

Read¶

To read a single Account Resource, clients may perform GET on a ec:account relation.

To read the Account List Resource, clients may perform GET on a ec:accounts relation or on the collection relation of a single Account resource.

In both cases, the success status code is 200 OK.

Example¶

{
  "accountID": "00000000-0000-4444-8888-000000000000",
  "created": "2014-12-04T17:00:38.208Z",
  "email": "test@abc.de",
  "hasPassword": true,
  "language": "en",
  "openID": [ ],
  "state": "active",
  "permissions": [
    "a:b:c",
    "d:e:f
  ],
  "groups": [
    {
      "name": "datamanager-user",
      "groupID": "fc8aff95-fd00-4f98-ac06-61659b48657b",
      "permissions": [
        "dm-create"
      ]
    },
    {
      "name": "appserver-user"
      "groupID": "a6b78f95-fd00-4f98-ac06-61659b45f3e2",
      "permissions": [
        "app-create",
        "app:platform-create:web"
      ]
    }
  ]
  "_links": {
    "self": {
      "href": "https://accounts.entrecode.de/account?accountID=00000000-0000-4444-8888-000000000000"
    },
    "curies": {
      "href": "https://entrecode.de/doc/rel/{rel}",
      "templated": true
    },
    "ec:account/tokens": {
      "href": "https://accounts.entrecode.de/account/tokens?accountID=00000000-0000-4444-8888-000000000000"
    },
    "collection": {
      "href": "https://accounts.entrecode.de/accounts"
    }
  }
}

Create¶

To create a new Account Resource, the Signup process has to be executed. See ec:auth/register relation.

Edit¶

To update an existing Account Resource, clients may perform a PUT on ec:account or self at a single Account Resource. The JSON Schema for editing an Account is https://schema.entrecode.de/schema-acc/account-template.

All fields are optional and need their own permission. Fields where no permission is available will be ignored.

Permissions:

acc:edit:<uuid>:language,openid,password
acc:change-state:<uuid>
acc:set-permissions:acc:<uuid>

For setting permissions, additionally the permission acc:permissions:<permission> is needed. The permission acc:set-password:<uuid> enables changing the password without the need for oldPassword to be set.

Deleting an OAuth / OpenID Connect connection is only allowed if hasPassword is true or an other connection which is not pending exists. Adding a connection is not possible via PUT, instead a signup has to be done with an authenticated access token.

For changing email address or password, the according auth relations have to be used: Change eMail, Password reset. Both require validation over email.

Editing the groups array is not possible using the Account Resource. Sending the property with a PUT request has no effect. To add accounts to a group, the group resource has to be edited.

Note to deprecated isPrincess field: This field is not included anymore. Just add account to the Princesses group.

The success status code is 200 OK and the response body is the updated single Account resource.

Delete¶

Deletion is not possible at the moment. However, the state can be set to deleted.