Scriptura Engage Security Web API

Note

This API is only available on the Scriptura Management Server.

There are several endpoints for this API:

/auth/v2/accounts

GET Get a list of accounts

Parameters

Name Located in Description Type
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amount of account items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of account items that needs to be returned in the response. The size of the page is set by the query parameter page-size.

Integer
filter query

Enables filtering on account name.

String

Responses

200 Everything was fine and an XML response is to be found in the body.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<accounts count="1" href="/auth/v2/accounts">
  <account identifier="system" href="/auth/v2/accounts/system"/>
  <rules count="1" href="/auth/v2/accounts/rules"/>
</accounts>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

POST Create an account

Responses

201 Account was created.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
409 The account could not be created because there already exists an account with the same name.
415 The supplied Content-Type header value is not supported.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}

GET Get information about a specific account.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 Everything was fine and an XML response is to be found in the body.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<account identifier="system" href="/auth/v2/accounts/system">
  <groups count="1" href="/auth/v2/accounts/system/groups"/>
  <name>system</name>
  <permissions count="1" href="/auth/v2/accounts/system/permissions"/>
  <roles count="12" href="/auth/v2/accounts/system/roles"/>
  <rules count="6" href="/auth/v2/accounts/system/rules"/>
  <users count="10" href="/auth/v2/accounts/system/users"/>
</account>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create or update an account.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String

Responses

201 Account was created.
204 Account was updated.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
415 The supplied Content-Type header value is not supported.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete an account.

Parameters

Name Located in Description Type
accountname path
String

Responses

204 Account was deleted.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
415 The supplied Content-Type header value is not supported.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/permissions

GET Get information about the permissions of a specific account.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amount of permission items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of permission items that needs to be returned in the response. The size of the page is set by the query paramter page-size.

Integer
filter query

Enables filtering on permission name.

String

Responses

200 Everything was fine and an XML response is to be found in the body.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<permissions count="1" href="/auth/v2/accounts/system/permissions">
  <permission href="/auth/v2/accounts/system/permissions/*"/>
</permissions>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Update an account's permissions.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String

Responses

204 Account's permissions were updated.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
415 The supplied Content-Type header value is not supported.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete an account's permissions.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String

Responses

204 Account's permissions were deleted.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
415 The supplied Content-Type header value is not supported.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/permissions/{permission}

GET Get a specific permission of a specific account.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
permission path

The name of the permission to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 Everything was fine and an XML response is to be found in the body.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<permission href="/auth/v2/accounts/example-account/permissions/example:permission">example:permission</permission>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create or update a specific permission for a specific account.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
permission path

The name of the permission to create or update.

String

Responses

201 Permission was created.
204 Permission was updated.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a specific permission of a specific account.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
permission path

he name of the permission to delete.

String

Responses

204 The permission was deleted.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users

GET Get a list of users for a specific account.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amount of user items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of user items that needs to be returned in the response. The size of the page is et by the query parameter page-size.

Integer
filter query

Enables filtering on username.

String

Responses

200 Everything was fine and an XML response is to be found in the body.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<users count="10" href="/auth/v2/accounts/system/users">
  <user identifier="admin" href="/auth/v2/accounts/system/users/admin"/>
  <user identifier="anonymous" href="/auth/v2/accounts/system/users/anonymous"/>
  <user identifier="system.configuration" href="/auth/v2/accounts/system/users/system.configuration"/>
  <user identifier="system.discovery" href="/auth/v2/accounts/system/users/system.discovery"/>
  <user identifier="system.management" href="/auth/v2/accounts/system/users/system.management"/>
  <user identifier="system.resourceindexer" href="/auth/v2/accounts/system/users/system.resourceindexer"/>
  <user identifier="system.scriptura" href="/auth/v2/accounts/system/users/system.scriptura"/>
  <user identifier="system.server" href="/auth/v2/accounts/system/users/system.server"/>
  <user identifier="system.versioning" href="/auth/v2/accounts/system/users/system.versioning"/>
  <user identifier="test" href="/auth/v2/accounts/system/users/test"/>
</users>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

POST Create a user for a specific account.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String

Responses

201 Permission was created.
204 Permission was updated.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname.
409 There already exists a user with the provided name.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}

GET Get a user of a specific account.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

200 Everything was fine and an XML response is to be found in the body.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user identifier="example-user" href="/auth/v2/accounts/system/users/example-user">
  <account>system</account>
  <attributes count="1" href="/auth/v2/accounts/system/users/example-user/attributes"/>
  <clients count="0" href="/auth/v2/accounts/system/users/example-user/clients"/>
  <federations count="1" href="/auth/v2/accounts/system/users/example-user/federated"/>
  <groups count="1" href="/auth/v2/accounts/system/users/example-user/groups"/>
  <password></password>
  <permissions count="5" href="/auth/v2/accounts/system/users/example-user/permissions"/>
  <roles count="1" href="/auth/v2/accounts/system/users/example-user/roles"/>
  <name>example-user</name>
</user>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create or update a user's information.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 User was created.
204 User was updated.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
409 The account could not be created because there already exists an account with the same name.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a specific user of a specific account.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

204 The user was deleted.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/password

PUT Update a user's password.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

204 Password was updated.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a user's password.

Description


Parameters

Name Located in Description Type
accountname path

the name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

204 The user's password was deleted.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/attributes

GET Retrieve a user's attributes.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

Integer
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amount of permission items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of permission items that needs to be returned in the response. The size of the page is set by the query paramter page-size.

Integer
filter query

Enables filtering on permission name.

String

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<attributes count="1" href="/auth/v2/accounts/system/users/example-user/attributes">
  <attribute identifier="example-attribute-name" href="/auth/v2/accounts/system/users/example-user/attributes/example-attribute-name"/>
</attributes>
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

POST Add a single user attribute to the user's user attribute collection.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 The user's user attribute was created.
400 The request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
409 There already exists a user attribute with the provided name.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create / update a user's complete user attribute collection.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 The user's attributes were created.
204 The user's user attributes were updated.
400 The request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 Not Found: No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a user's complete user attribute collection.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

204 The user's user attributes were updated.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/attributes/{attributename}

GET Retrieve a specific user attribute.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
attributename path

The name of the user attribute to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<attribute identifier="example-attribute-name" href="/auth/v2/accounts/system/users/example-user/attributes/example-attribute-name">
  <id>356</id>
  <name>example-attribute-name</name>
  <value>example-attribute-value</value>
</attribute>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no user attribute could be found with the provided attributename.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create / update the specified user attribute.

Description


Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
attributename path

The name of the user attribute to be retrieved.

String

Responses

201 The user attribute was created.
204 The user's user attributes were updated.
400 The supplied XML data was invalid.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no user attribute could be found with the provided attributename.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a user attribute.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
attributename path

the name of the user attribute to be retrieved.

String

Responses

204 The user's user attribute was deleted.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no user attribute could be found with the provided attributename.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/roles

GET Retrieve a user's roles.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amout of role items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of role items that needs to be returned in the repsonse. The size of the page is set by the query parameter page-size.

Integer
filter query

Enables filtering on role name.

String

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<roles count="1" href="/auth/v2/accounts/system/users/example-user/roles">
  <role identifier="userrole" href="/auth/v2/accounts/system/users/example-user/roles/userrole"/>
</roles>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues

POST Add a single user role to the user's roles collection.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 The user's attribute was created.
400 The request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
409 There already exists a role with the provided name.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create / update a user's complete role collection.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 The user's roles were created.
204 The user's role were updated.
400 The request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a user's complete role collection.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 The user's roles were created.
204 The user's role were updated.
400 The request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/roles/{rolename}

GET Retrieve a specific user attribute.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
rolename path

The name of the role to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<role identifier="userrole" href="/auth/v2/accounts/system/roles/userrole">
  <name>userrole</name>
  <permissions count="5" href="/auth/v2/accounts/system/roles/userrole/permissions"/>
</role>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no role could be found with the provided rolename.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create / update the specified user attribute.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
rolename path

The name of the role to be retrieved.

String

Responses

201 The role was added to the user.
204 The role was updated for the user.
400 The request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no role could be found with the provided rolename.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a user's role.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
rolename path

The name of the role to be retrieved.

String

Responses

204 The user's role was deleted.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no role could be found with the provided rolename.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/groups

GET Retrieve a user's groups.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amount of user items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of user items that needs to be returned in the response. The size of the page is et by the query parameter page-size.

Integer
filter query

Enables filtering on username.

String

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<groups count="1" href="/auth/v2/accounts/system/users/example-user/groups">
  <group identifier="users" href="/auth/v2/accounts/system/users/example-user/groups/users"/>
</groups>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

POST Add a single user group to the user's groups collection.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 The user's group was added.
400 the request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
409 There already has a group with the provided name.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create / update a user's complete group collection.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 The user's groups were created.
204 The user's groups were updated.
400 The request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a user's complete group collection.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

204 The user's groups were deleted.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/groups/{groupname}

GET Retrieve a user's groups.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
groupname path

The name of the group to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<group identifier="users" href="/auth/v2/accounts/system/users/example-user/groups/users">
  <name>users</name>
  <roles count="1" href="/auth/v2/accounts/system/groups/users/roles"/>
  <users count="1" href="/auth/v2/accounts/system/groups/users/users"/>
</group>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no group could be found with the provided groupname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

PUT Create / update the specified group.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
groupname path

The name of the group to be retrieved.

String

Responses

201 The group was added to the user.
204 The group was updated for the user.
400 The request body contains invalid XML.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no group could be found with the provided groupname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a user's group.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
groupname path

The name of the group to be retrieved.

String

Responses

204 The user's group was deleted.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname, no user could be found with the provided username or no group could be found with the provided groupname.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/permissions

GET Retrieve a user's list of permissions.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amount of account items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of account items that needs to be returned in the response. The size of the page is set by the query parameter page-size.

Integer
filter query

Enables filtering on account name.

String

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<permissions count="5" href="/auth/v2/accounts/system/users/example-user/permissions">
  <permission href="/auth/v2/accounts/system/users/example-user/permissions/auth:accounts:read"/>
  <permission href="/auth/v2/accounts/system/users/example-user/permissions/auth:me:*:read"/>
  <permission href="/auth/v2/accounts/system/users/example-user/permissions/auth:me:attributes:update"/>
  <permission href="/auth/v2/accounts/system/users/example-user/permissions/auth:me:password:create"/>
  <permission href="/auth/v2/accounts/system/users/example-user/permissions/auth:me:read"/>
</permissions>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/permissions/{permissionname}

GET Retrieve a user's list of permissions.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
permissionname path

The name of the permission to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>				
<permission href="/auth/v2/accounts/system/users/example-user/permissions/auth:accounts:read">auth:accounts:read</permission>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/accounts/{accountname}/users/{username}/clients

GET Retrieve a user's list of clients.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amount of account items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of account items that needs to be returned in the response. The size of the page is set by the query parameter page-size.

Integer
filter query

Enables filtering on account name.

String

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<clients count="2" href="/auth/v2/accounts/system/users/example-user/clients">
  <client identifier="0w2A-FFKGz9b8YqjzN-y" href="/auth/v2/accounts/system/users/example-user/clients/0w2A-FFKGz9b8YqjzN-y"/>
  <client identifier="Mpd9o4tQjKHT5roiA4FF" href="/auth/v2/accounts/system/users/example-user/clients/Mpd9o4tQjKHT5roiA4FF"/>
</clients>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

POST Create / update a user's client information.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

201 The client has been created.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<client identifier="JU13MNkWhAkaVL-TKlT0" href="/auth/v2/accounts/system/users/example-user/clients/JU13MNkWhAkaVL-TKlT0">
    <client-id>JU13MNkWhAkaVL-TKlT0</client-id>
    <client-secret>BV96ZChw1ZEw0YWRgprb2ajckhaoa3DWm0v6REPl</client-secret>
    <description>Example description.</description>
    <uris count="1" href="/auth/v2/accounts/system/users/example-user/clients/JU13MNkWhAkaVL-TKlT0/uris">
        <uri>http://example.com/</uri>
    </uris>
</client>
204 The client has been updated.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username. It's also possible that the provided value in the client-id element doesn't exist.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

DELETE Delete a user's clients.

Parameters

Name Located in Description Type
accountname path

The name of the account to be retrieved.

String
username path

The name of the user to be retrieved.

String

Responses

204 The user's clients have been deleted.
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No account could be found with the provided accountname or no user could be found with the provided username.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/federated

GET Retrieve a list of all federated types.

Parameters

Name Located in Description Type
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<federations count="1" href="/auth/v2/federated">
  <federation identifier="email" href="/auth/v2/federated/email"/>
</federations>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/federated/{type}

GET Retrieve a specific federation type.

Parameters

Name Located in Description Type
type path

The type of federation to retrieve.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<federation identifier="email" href="/auth/v2/federated/email">
  <federated-users count="1" href="/auth/v2/federated/email/principals"/>
  <type>email</type>
</federation>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No federation type could be found with the provided type.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/federated/{type}/principals

GET Retrieve the list of principals of a specific federation type.

Parameters

Name Located in Description Type
type path

The type of federation to retrieve.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer
page-size query

The amount of account items that will be returned in a single response.

Integer
current-page query

This value denotes the ‘page’ of account items that needs to be returned in the response. The size of the page is set by the query parameter page-size.

Integer
filter query

Enables filtering on account name.

String

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<federated-users count="1" href="/auth/v2/federated/email/principals">
  <federated-user identifier="admin@localhost" href="/auth/v2/federated/email/principals/admin@localhost"/>
</federated-users>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No federation type could be found with the provided type.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/federated/{type}/principals/{principal}

GET Retrieve the information of a specific federated user.

Parameters

Name Located in Description Type
type path

The type of federation to retrieve.

String
principal path

The federated user to retrieve.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<federated-user identifier="admin@localhost" href="/auth/v2/federated/email/principals/admin@localhost">
  <attributes count="2" href="/auth/v2/federated/email/principals/admin@localhost/attributes"/>
  <principal>admin@localhost</principal>
  <type>email</type>
  <users count="1" href="/auth/v2/federated/email/principals/admin@localhost/users"/>
</federated-user>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No federation type could be found with the provided type or no federated user could be found with the provided principal.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/federated/{type}/principals/{principal}/attributes

GET Retrieve a list of attributes of a specific federated user.

Parameters

Name Located in Description Type
type path

The type of federation to retrieve.

String
principal path

The federated user to retrieve.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<attributes count="2" href="/auth/v2/federated/email/principals/admin@localhost/attributes">
  <attribute identifier="default-user" href="/auth/v2/federated/email/principals/admin@localhost/attributes/default-user"/>
  <attribute identifier="password" href="/auth/v2/federated/email/principals/admin@localhost/attributes/password"/>
</attributes>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No federation type could be found with the provided type or no federated user could be found with the provided principal.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/federated/{type}/principals/{principal}/attributes/{attributename}

GET Retrieve a list of attributes of a specific federated user.

Parameters

Name Located in Description Type
type path

The type of federation to retrieve.

String
principal path

The federated user to retrieve.

String
attributename path

The federated user attribute to retrieve.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<attribute identifier="default-user" href="/auth/v2/federated/email/principals/admin@localhost/attributes/default-user">
  <id>35</id>
  <name>default-user</name>
  <value>system\admin</value>
</attribute>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No federation type could be found with the provided type, no federated user could be found with the provided principal or no federated user attribute could be found with the provided attributename.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.

/auth/v2/federated/{type}/principals/{principal}/users

GET Retrieve a list of attributes of a specific federated user.

Parameters

Name Located in Description Type
type path

The type of federation to retrieve.

String
principal path

The federated user to retrieve.

String
depth query

This value denotes the level depth of the XML response. Increasing this value will reveal more children of the XML response, but will also have a performance penalty because more information needs to be looked up and transmitted.

Integer

Responses

200 The request has succeeded. The requested entity is returned within the response.

Examples

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<users count="1" href="/auth/v2/federated/email/principals/admin@localhost/users">
  <user identifier="admin" href="/auth/v2/accounts/system/users/admin"/>
</users>
401 The supplied access token is either invalid, doesn't contain the needed permissions or is expired.
404 No federation type could be found with the provided type or no federated user could be found with the provided principal.
500 The server failed to complete the request without error. The server logs should point out what went wrong.
503 The server was unable to respond in time due to connection issues.