-
Notifications
You must be signed in to change notification settings - Fork 0
Users
Users describes the 2cloud account of a registered user. There should only ever be one User object per physical person.
The User resource is represented in responses under the users property. The users property will be an array of Users.
Users appear as follows:
{
"id": uint64,
"username": string,
"email": string,
"email_unconfirmed": bool,
"secret": string,
"joined": datetime,
"name": {
"given": string,
"family": string
},
"last_active": datetime,
"admin": bool,
"receives_newsletter": bool
}
Mutable properties are properties that can be modified through interactions with the API.
- username: A memorable, user-chosen identifier. This is not guaranteed to persist over time.
- email: The email address the user would like to receive important announcements at.
-
name: A JSON object containing the following properties:
- given: The given or first name of the user.
- family: the family or last name of the user.
- admin: True if the user has administrative access on this server, False or omitted if the user does not.
- receives_newsletter: True if the user has opted into periodic updates from the administrators, False if they have opted out.
Immutable properties are properties that are created and modified only by the system; there is no way to modify them through the API.
- id: A unique, immutable identifier for this user.
- email_unconfirmed: True if the email address still needs to be confirmed, False or omitted if the address no longer needs to be confirmed.
- secret: An authentication token used as a password to access this account.
- joined: The timestamp the user registered their account, expressed according to RFC 3339.
- last_active: The date and time a user last was observed to be actively engaging with the service, expressed according to RFC 3339.
This request requires administrative credentials. It will reply with a 403 error if the authorising user does not have administrative access to the server.
GET /users
The following URL parameters are accepted when listing Users, and will filter the list accordingly:
- active_after: the lower bound on when a User was last active. This should be specified as a URL-encoded ISO 8601 timestamp. Only Users active after the specified date will be returned.
- active_before: the upper bound on when a User was last active. This should be specified as a URL-encoded ISO 8601 timestamp. Only Users active before the specified date will be returned.
- joined_after: the lower bound on when a User registered. This should be specified as a URL-encoded ISO 8601 timestamp. Only Users who joined after the specified date will be returned.
- joined_before: the upper bound on when a User registered. This should be specified as a URL-encoded ISO 8601 timestamp. Only Users who joined before the specified date will be returned.
- count: the maximum number of Users to return, as an integer. Defaults to 20, with a maximum of 100.
Note that if joined_after or joined_before is specified, active_after and active_before will be ignored.
Results will be ordered depending on the parameters that are specified. If more than one group of parameters is specified, whatever is lower in the below list will take precedence.
- If no parameters, joined_after, or joined_before is specified, the results will be ordered by the User's
joinedproperty, descending. - If active_after or active_before is specified, the results will be ordered by the User's
last_activeproperty, descending.
This request sets the Last-Modified header to the latest last_active property of the Users returned.
The Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
This request returns a list of user resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of users",
"users": [
{
// See the User Resource for the contents of this part
},
{
// See the User Resource for the contents of this part
}
]
}
In the event no users are to be returned (none matched the filter combination of the query parameters), an empty array will be returned.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 403 | ERROR_ACCESS_DENIED | Authenticating user does not have access to the user list. | |
| 400 | ERROR_INVALID_FORMAT | count | The count parameter was not an integer. |
| 400 | ERROR_TOO_LONG | count | The count parameter must be less than or equal to 100. |
| 400 | ERROR_TOO_SHORT | count | The count parameter must be greater than 0. |
| 400 | ERROR_INVALID_FORMAT | active_after | The active_after parameter was not a valid RFC 3339 date. |
| 400 | ERROR_INVALID_FORMAT | active_before | The active_before parameter was not a valid RFC 3339 date. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_INVALID_FORMAT | joined_after | The joined_after parameter was not a valid RFC 3339 date. |
| 400 | ERROR_INVALID_FORMAT | joined_before | The joined_before parameter was not a valid RFC 3339 date. |
This request requires only authentication if it is run against the profile of the authenticating user. If it is run against another user's profile, it requires administrative credentials.
GET /users/{username}
This request sets the Last-Modified header to the last_active property of the User returned.
The Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
This request returns a list of user resources as a JSON array. The array will only have one item:
{
"code": 200,
"msg": "Successfully retrieved user information",
"users": [
{
// See the User Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | No username was supplied. |
| 403 | ERROR_ACCESS_DENIED | Authenticating user does not have access the information of the specified user. | |
| 404 | ERROR_NOT_FOUND | user | The specified username did not correspond to any user. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. |
Before a User can be created, an Account must be created to associate with the User. See the Accounts documentation for information on creating an Account.
POST /users
Because this request occurs before the User has credentials, neither the From nor the Authorization headers need to be set, unless an administrator is registering an account on behalf of another user. The User-Agent, Content-Type, and Content-Length headers, however, need to be set.
The request body should be a User Resource and an Account Resource.
In the User Resource, only the Mutable Properties will be used; the rest will be ignored. Furthermore, the admin property will only be used if the request is authorised by a User with admin credentials. Otherwise, it will be ignored.
In the Account Resource, only the ID property will be used; the rest will be ignored.
A sample request body:
{
"user": {
"username": "myusername",
"email": "[email protected]",
"name": {
"given": "Test",
"family": "User"
}
},
"account": {
"id": "someaccountIDgoeshere"
}
}
This request sets the Last-Modified header to the last_active property of the User returned.
The Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
This request returns a list of user resources as a JSON array. The array will only have one item—the User that was created:
{
"code": 201,
"msg": "Successfully created a user account",
"users": [
{
// See the User Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_BAD_REQUEST_FORMAT | The body of the request was not valid JSON. | |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_MISSING_PARAM | account.id | No account ID was supplied. |
| 400 | ERROR_MISSING_PARAM | user | No user object was supplied. |
| 400 | ERROR_INVALID_VALUE | account.id | The supplied account ID was not valid. |
| 409 | ERROR_ALREADY_IN_USE | account | The supplied account ID belongs to an account that is already associated with a user. |
| 400 | ERROR_MISSING_PARAM | user.username | No username was supplied. |
| 400 | ERROR_MISSING_PARAM | user.email | No email address was supplied. |
| 409 | ERROR_ALREADY_IN_USE | user.username | The specified username is already in use. |
| 400 | ERROR_INVALID_VALUE | user.username | The specified username contains an invalid character. |
| 400 | ERROR_TOO_SHORT | user.username | The specified username was too short. |
| 400 | ERROR_TOO_LONG | user.username | The specified username was too long. |
This request requires only authentication if it is run against the profile of the authenticating user. If it is run against another user's profile, it requires administrative credentials.
PUT /users/{username}
Because this request has a body, the Content-Type, and Content-Length headers need to be set.
The request body should be a User Resource. Only the Mutable Properties will be used; the rest will be ignored. Furthermore, the admin property will only be used if the request is authorised by a User with admin credentials. Otherwise, it will be ignored. Finally, the username property cannot be modified in this request.
A sample request body:
{
"user": {
"email": "[email protected]",
"name": {
"given": "Test",
"family": "User"
}
}
}
This request sets the Last-Modified header to the last_active property of the User returned.
The Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
This request returns a list of user resources as a JSON array. The array will only have one item—the User that was modified:
{
"code": 200,
"msg": "Successfully updated the user account",
"users": [
{
// See the User Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | No username was specified. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user does not have access to the specified user's information. | |
| 404 | ERROR_NOT_FOUND | user | The supplied username did not correspond to a user. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_BAD_REQUEST_FORMAT | The body of the request was not valid JSON. | |
| 400 | ERROR_MISSING_PARAM | user | The request did not include a user object. |
| 403 | ERROR_ACCESS_DENIED | user.admin | Only administrators can grant or revoke administrator status, and the authenticating user was not an administrator. |
| 400 | ERROR_MISSING_PARAM | user.email | The email parameter cannot be blank. It must be specified or omitted. |
This request requires only authentication if it is run against the profile of the authenticating user. If it is run against another user's profile, it requires administrative credentials.
PUT /users/{username}/verify
Because this request has a body, the Content-Type, and Content-Length headers need to be set.
The request body should be a JSON object with a code property that contains the verification code that was emailed to the user.
A sample request body:
{
"email_verification": {
"code": "Insert verification code here"
}
}
This request sets the Last-Modified header to the last_active property of the User returned.
The Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
This request returns a list of user resources as a JSON array. The array will only have one item—the User whose email was verified:
{
"code": 200,
"msg": "Successfully verified email address",
"users": [
{
// See the User Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | No username was specified. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user did not have access to verify the specified user's email address. | |
| 404 | ERROR_NOT_FOUND | user | The specified username did not correspond to a user. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_BAD_REQUEST_FORMAT | The request body was not valid JSON. | |
| 400 | ERROR_MISSING_PARAM | email_verification.code | The email verification code was not set. |
| 400 | ERROR_INVALID_VALUE | email_verification.code | The email verification code was not correct. |
This request requires only authentication if it is run against the profile of the authenticating user. If it is run against another user's profile, it requires administrative credentials.
POST /users/{username}/secret
This request requires an empty body.
This request sets the Last-Modified header to the last_active property of the User returned.
The Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
This request returns a list of User resources as a JSON array. The array will only have one item—the User whose secret was reset.
{
"code": 200,
"msg": "Successfully reset secret",
"users": [
{
// See the User Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | No username was supplied. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user does not have access to reset the specified user's secret. | |
| 404 | ERROR_NOT_FOUND | user | No user was found that corresponded to the specified username. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. |
This request requires only authentication if it is run against the profile of the authenticating user. If it is run against another user's profile, it requires administrative credentials.
DELETE /users/{username}
This request sets the Last-Modified header to the last_active property of the User returned.
The Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.
This request returns a list of user resources as a JSON array. The array will only have one item—the User that was just deleted:
{
"code": 200,
"msg": "Successfully deleted the user",
"users": [
{
// See the User Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | No username was supplied. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user does not have access to delete the specified user. | |
| 404 | ERROR_NOT_FOUND | user | No user was found that corresponded to the specified username. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. |