Accounts API

From PowerFolder Wiki
Jump to: navigation, search

Contents

Preface

The accounts API is designed to create, remove and change user accounts. It's also possible to change the access permissions of users to folders. Please read the general API documentation for a general understanding of the PowerFolder API.

Web URL

The service is reachable at the URI: /api/accounts

Example: http://myserver.com/api/accounts

Authorization / Security

Calls of the API always require an authorized caller. This is done by basic access authorization which must be added to each call. It's required to authenticate as admin.

Action: getInfo

This action returns basic information of an account. Existing accounts will be search by "ID" first then "username".

Parameter Mandatory Description Example
action Yes Must always be "getInfo" getInfo
username Yes The username / email of the user. user@somehost.com
ID No The universal unique ID of the account. Will use this ID to resolve/create the user account. Can be any external ID if unique. PME2myo2355sRegfgKk8m0YdA


Example

http://myserver.com:8080/api/accounts?action=getInfo&username=user@somehost.com


Return value 

{
  "ID":"TruJsi69ag6ar2fVC1SF",
  "username":"user@somehost.com",
  "lastLogin":null,
  "created":"2012-02-13 03:11:37.725",
  "notes":"Example note",
  "nFolder":2,
  "nFolderOwner":1,
  "spaceAllowed":5368709120,
  "spaceUsed":514229,
  "devicesAllowed":8,
  "devicesUsed":2,
  "serverID":"6bzY8niQKaNEg7xGnog"
}
Result key Description Example
ID Account ID 3GYXgyusXuNoHd88qgWp
username Account username user@company.de
created Date the account was created 2011-02-13 03:11:37.725
lastLogin The last login date 2012-02-13 03:11:37.725
notes Custom text notes This user is valueable
nFolder Number of folders the account is member of 8
nFolderOwner Number of folders the account is owner of 2
spaceAllowed The space allowed/quota for this account in bytes. 5368709120
spaceUsed The space/quota used by this account in bytes. 514229
devicesAllowed The number of devices this account can be used on. 8
devicesUsed The number of actual used devices by this account. 2
serverID The server ID this account in bound to. Only for clustered setup. 6bzY8niQKaNEg7xGnog

Action: getFolderPermissions

This action returns information about the folders and permissions of an account. Existing accounts will be search by "ID" first then "username".

Parameter Mandatory Description Example
action Yes Must always be "getFolderPermissions" getFolderPermissions
username Yes The username / email of the user. user@somehost.com
ID No The universal unique ID of the account. Will use this ID to resolve/create the user account. Can be any external ID if unique. PME2myo2355sRegfgKk8m0YdA


Example

http://myserver.com:8080/api/accounts?action=getFolderPermissions&username=user@somehost.com


Return value 

{
  "ResultSet":{
     "Result":[
        {
           "folderID":"5LhiBzxp9Uz5698n339Y",
           "folderName":"Documents",
           "permission":"OWNER",
           "resourceURL":"https://myserver.com/files/NUxoaUJ6eHA5VXo1Njk4bjMzOVk="
        },
        {
           "folderID":"UhpBitrekB9Tk3z1gSVz",
           "folderName":"Project 987",
           "permission":"ADMIN",
           "resourceURL":"https://myserver.com/files/VWhwQml0cmVrQjlUazN6MWdTVno="
        },
        {
           "folderID":"HK6gWAX1BVKYFm4UN82i",
           "folderName":"Sales material",
           "permission":"READ",
           "resourceURL":"https://myserver.com/files/SEs2Z1dBWDFCVktZRm00VU44Mmk="
        }
     ]
  }
}
Result key Description Example
folderID Folder ID UhpBitrekB9Tk3z1gSVz
folderName Name of the folder Sales material
permission The permission on that folder: NO_ACCESS, READ, READ_WRITE, ADMIN or OWNER ADMIN
resourceURL The URL the folder is available at. https://myserver.com/files/VWhwQml0cmVrQjlUazN6MWdTVno=

Action: store

This action is for creating or changing user account. If the user account does not exists one will be created. If an user account can be found it will be updated with the new values. Existing accounts will be search by "ID" first then "username".

Parameter Mandatory Description Example
action Yes Must always be "store" store
username Yes The username / email of the user. user@somehost.com
ID No The universal unique ID of the account. Will use this ID to resolve/create the user account. Can be any external ID if unique. PME2myo2355sRegfgKk8m0YdA
password No The password to set. §ac0mpl3x_p4ssw0rd!
notes No The notes to set This is a example note
spaceAllowed No The space/quota for this user in bytes. "-1" for unlimited 5368709120
devicesAllowed No The maximum number of allowed devices to license. "999" for unlimited. 1
validTill No The date to which the user account is valid. In ISO format DD-MMM-YYYY. 21-DEC-2012
serverID No The ID of the server in cluster the user will connected to. If omitted the server, which received the request, will be used. 6bzY8niQKaNEg7xGnog


Example

http://myserver.com:8080/api/accounts?action=store&username=user@somehost.com&password=newpassword&spaceBytes=5368709120&licenseDevices=5


Return value 

{
 "ID":"PME2myo2355sRegfgKk8m0YdA",
 "username":"user@somehost.com",
 "message":"Successfully stored user"
}

Action: grant

For granting extra user permissions of the Extended Security Control.

Parameter Mandatory Description Example
action Yes Must always be "grant" grant
username Yes, if "ID" is missing The username / email of the user. user@somehost.com
ID Yes, if "username" missing The universal unique ID of the account. PME2myo2355sRegfgKk8m0YdA
permissionID Yes Name of the permission to set (full list). Multiple values allowed. FolderCreate


Example

http://myserver.com:8080/api/accounts?action=grant&username=user@somehost.com&permissionID=FolderCreate&permissionID=ChangePreferences


Return value 

{
 "ID":"PME2myo2355sRegfgKk8m0YdA",
 "username":"user@somehost.com",
 "message":"user@somehost.com granted FolderCreatePermission"
}

Action: revoke

For revoking extra user permissions of the Extended Security Control.

Parameter Mandatory Description Example
action Yes Must always be "revoke" revoke
username Yes, if "ID" is missing The username / email of the user. user@somehost.com
ID Yes, if "username" missing The universal unique ID of the account. PME2myo2355sRegfgKk8m0YdA
permissionID Yes Name of the permission to set (full list). Multiple values allowed. FolderCreate


Example

http://myserver.com:8080/api/accounts?action=revoke&username=user@somehost.com&permissionID=FolderCreate&permissionID=ChangePreferences


Return value 

{
 "ID":"PME2myo2355sRegfgKk8m0YdA",
 "username":"user@somehost.com",
 "message":"user@somehost.com revoked FolderCreatePermission"
}

Action: getLoginURL

Retrieves an auto-login URL for a user account. E.g. for single sign on from other web portals or pages. Related documentation: Login callback API.

Parameter Mandatory Description Example
action Yes Must always be "getLoginURL" getLoginURL
username Yes The username / email of the user. user@somehost.com
ID No The universal unique ID of the account. Will use this ID to resolve/create the user account. Can be any external ID if unique. PME2myo2355sRegfgKk8m0YdA
password Yes The password/credentials of that user account. 3 chicken ate my bag


Example

http://myserver.com:8080/api/accounts?action=getLoginURL&username=user@somehost.com&password=3%20chicken%20ate%20my%20bag


Return value 

{
 "ID":"PME2myo2355sRegfgKk8m0YdA",
 "username":"user@somehost.com",
 "loginURL":"http://myserver:8080/login?Username=user@somehost.com&PasswordOBF=GAlIQUJIQE5DWAlKXQlGUglOTEw%3D"
}

Related documentation

Retrieved from "http://www.powerfolder.com/w/index.php?title=Accounts_API&oldid=3925"
Personal tools
Navigation