Page tree
Skip to end of metadata
Go to start of metadata
{ "swagger": "2.0", "info": { "description": "The User Management API provides the ability to manage user accounts, access, and permissions.", "version": "1.7.4.1", "title": "XNAT User API" }, "tags": [ { "name": "users-api", "description": "User Management API" } ], "definitions": { "HttpSession": { "type": "object", "properties": {} }, "User": { "type": "object", "properties": { "admin": { "type": "boolean", "description": "Whether the user is a site administrator." }, "authorization": { "description": "The user's authorization record used when logging in.", "$ref": "#\/definitions\/UserAuthI" }, "email": { "type": "string", "description": "The user's email address." }, "enabled": { "type": "boolean", "description": "Whether the user is enabled." }, "firstName": { "type": "string", "description": "The user's first name." }, "id": { "type": "integer", "format": "int32", "description": "The user's unique key." }, "lastModified": { "type": "string", "format": "date-time", "description": "The date and time the user record was last modified." }, "lastName": { "type": "string", "description": "The user's last name." }, "password": { "type": "string", "description": "The user's encrypted password." }, "salt": { "type": "string", "description": "The salt used to encrypt the user's password." }, "secured": { "type": "boolean", "description": "Indicates whether the user object is secured, which causes secure fields like password and salt to return null." }, "username": { "type": "string", "description": "The user's login name." }, "verified": { "type": "boolean", "description": "Whether the user is verified." } }, "description": "Contains the properties that define a user on the system." }, "Collection": { "type": "object" }, "UserAuthI": { "type": "object", "properties": { "authMethod": { "type": "string" }, "authMethodId": { "type": "string" }, "authUser": { "type": "string" }, "enabled": { "type": "boolean" }, "failedLoginAttempts": { "type": "integer", "format": "int32" }, "lastLoginAttempt": { "type": "string", "format": "date-time" }, "lastSuccessfulLogin": { "type": "string", "format": "date-time" }, "passwordUpdated": { "type": "string", "format": "date-time" }, "xdatUsername": { "type": "string" } } } }, "paths": { "/xapi/users": { "get": { "tags": ["users-api"], "summary": "Get list of users.", "description": "The primary users function returns a list of all users of the XNAT system. This includes just the username and nothing else. You can retrieve a particular user by adding the username to the REST API URL or a list of users with abbreviated user profiles by calling /xapi/users/profiles.", "operationId": "usersGetUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "responses": { "200": { "description": "A list of usernames.", "schema": { "type": "array", "items": {"type": "string"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "You do not have sufficient permissions to access the list of usernames."}, "404": {"description": "Not Found"} } }, "post": { "tags": ["users-api"], "summary": "Updates the user object with the specified username.", "description": "Returns the updated serialized user object with the specified username.", "operationId": "createUserUsingPOST", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [{ "in": "body", "name": "model", "description": "model", "required": true, "schema": {"$ref": "#/definitions/User"} }], "responses": { "200": { "description": "OK", "schema": {"$ref": "#/definitions/User"} }, "201": { "description": "User successfully created.", "schema": {"$ref": "#/definitions/User"} }, "400": {"description": "The submitted data was invalid."}, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to update this user."}, "404": {"description": "Not Found"} } } }, "/xapi/users/active": {"get": { "tags": ["users-api"], "summary": "Get list of active users.", "description": "Returns a map of usernames for users that have at least one currently active session, i.e. logged in or associated with a valid application session. The number of active sessions and a list of the session IDs is associated with each user.", "operationId": "getActiveUsersUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "responses": { "200": { "description": "A list of active users.", "schema": {"type": "object"} }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "You do not have sufficient permissions to access the list of usernames."}, "404": {"description": "Not Found"} } }}, "/xapi/users/active/{username}": { "get": { "tags": ["users-api"], "summary": "Get information about active sessions for the indicated user.", "description": "Returns a map containing a list of session IDs and usernames for users that have at least one currently active session, i.e. logged in or associated with a valid application session. This also includes the number of active sessions for each user.", "operationId": "getUserActiveSessionsUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [{ "name": "username", "in": "path", "description": "ID of the user to fetch", "required": true, "type": "string" }], "responses": { "200": { "description": "A list of active users.", "schema": { "type": "array", "items": {"type": "string"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "You do not have sufficient permissions to access this user's sessions."}, "404": {"description": "The indicated user has no active sessions or is not a valid user."} } }, "delete": { "tags": ["users-api"], "summary": "Invalidates all active sessions associated with the specified username.", "description": "Returns a list of session IDs that were invalidated.", "operationId": "invalidateUserUsingDELETE", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "in": "body", "name": "current", "description": "current", "required": false, "schema": {"$ref": "#/definitions/HttpSession"} }, { "name": "username", "in": "path", "description": "The username of the user to invalidate.", "required": true, "type": "string" } ], "responses": { "200": { "description": "User successfully invalidated.", "schema": { "type": "array", "items": {"type": "string"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "204": {"description": "No Content"}, "304": {"description": "Indicated user has no active sessions, so no action was taken."}, "403": {"description": "Not authorized to invalidate this user's sessions."}, "404": {"description": "User not found."} } } }, "/xapi/users/current": {"get": { "tags": ["users-api"], "summary": "Get list of users who are enabled or who have interacted with the site somewhat recently.", "description": "The users' profiles function returns a list of all users of the XNAT system with brief information about each.", "operationId": "currentUsersProfilesGetUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "responses": { "200": { "description": "A list of user profiles.", "schema": { "type": "array", "items": {"$ref": "#/definitions/User"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "You do not have sufficient permissions to access the list of usernames."}, "404": {"description": "Not Found"} } }}, "/xapi/users/profile/{username}": {"get": { "tags": ["users-api"], "summary": "Get user profile.", "description": "The user profile function returns a user of the XNAT system with brief information.", "operationId": "usersProfileGetUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [{ "name": "username", "in": "path", "description": "ID of the user to fetch", "required": true, "type": "string" }], "responses": { "200": { "description": "A user profile.", "schema": { "type": "array", "items": {"$ref": "#/definitions/User"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "You do not have sufficient permissions to access the user profile."}, "404": {"description": "Not Found"} } }}, "/xapi/users/profiles": {"get": { "tags": ["users-api"], "summary": "Get list of user profiles.", "description": "The users' profiles function returns a list of all users of the XNAT system with brief information about each.", "operationId": "usersProfilesGetUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "responses": { "200": { "description": "A list of user profiles.", "schema": { "type": "array", "items": {"$ref": "#/definitions/User"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "You do not have sufficient permissions to access the list of users."}, "404": {"description": "Not Found"} } }}, "/xapi/users/{username}": { "get": { "tags": ["users-api"], "summary": "Gets the user with the specified user ID.", "description": "Returns the serialized user object with the specified user ID.", "operationId": "getUserUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [{ "name": "username", "in": "path", "description": "Username of the user to fetch.", "required": true, "type": "string" }], "responses": { "200": { "description": "User successfully retrieved.", "schema": {"$ref": "#/definitions/User"} }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to view this user."}, "404": {"description": "User not found."} } }, "put": { "tags": ["users-api"], "summary": "Updates the user object with the specified username.", "description": "Returns the updated serialized user object with the specified username.", "operationId": "updateUserUsingPUT", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "The username of the user to create or update.", "required": true, "type": "string" }, { "in": "body", "name": "model", "description": "model", "required": true, "schema": {"$ref": "#/definitions/User"} } ], "responses": { "200": { "description": "User successfully updated.", "schema": {"$ref": "#/definitions/User"} }, "201": {"description": "Created"}, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "304": {"description": "The user object was not modified because no attributes were changed."}, "403": {"description": "Not authorized to update this user."}, "404": {"description": "User not found."} } } }, "/xapi/users/{username}/enabled": {"get": { "tags": ["users-api"], "summary": "Returns whether the user with the specified user ID is enabled.", "description": "Returns true or false based on whether the specified user is enabled or not.", "operationId": "usersIdEnabledGetUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [{ "name": "username", "in": "path", "description": "The ID of the user to retrieve the enabled status for.", "required": true, "type": "string" }], "responses": { "200": { "description": "User enabled status successfully retrieved.", "schema": {"type": "boolean"} }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to get whether this user is enabled."}, "404": {"description": "User not found."} } }}, "/xapi/users/{username}/enabled/{flag}": {"put": { "tags": ["users-api"], "summary": "Sets the user's enabled state.", "description": "Sets the enabled state of the user with the specified user ID to the value of the flag parameter.", "operationId": "usersIdEnabledFlagPutUsingPUT", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to fetch", "required": true, "type": "string" }, { "name": "flag", "in": "path", "description": "The value to set for the enabled status.", "required": true, "type": "boolean" } ], "responses": { "200": { "description": "User enabled status successfully set.", "schema": {"type": "boolean"} }, "201": {"description": "Created"}, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to enable or disable this user."}, "404": {"description": "User not found."} } }}, "/xapi/users/{username}/groups": { "get": { "tags": ["users-api"], "summary": "Returns the groups for the user with the specified user ID.", "description": "Returns a collection of the user's groups.", "operationId": "usersIdGroupsGetUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [{ "name": "username", "in": "path", "description": "The ID of the user to retrieve the groups for.", "required": true, "type": "string" }], "responses": { "200": { "description": "User groups successfully retrieved.", "schema": { "type": "array", "items": {"type": "object"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to get the groups for this user."}, "404": {"description": "User not found."} } }, "put": { "tags": ["users-api"], "summary": "Adds the user to one or more groups.", "description": "Assigns the user to one or more new groups.", "operationId": "usersIdAddGroupsUsingPUT", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to add to the specified groups", "required": true, "type": "string" }, { "in": "body", "name": "groups", "description": "The groups to which the user should be added.", "required": true, "schema": { "type": "array", "items": {"type": "string"} } } ], "responses": { "200": { "description": "User successfully added for all specified groups.", "schema": { "type": "array", "items": {"type": "string"} } }, "201": {"description": "Created"}, "202": { "description": "User was successfully added to some of the specified groups, but some may have failed. Check the return value for groups that the service was unable to add.", "schema": { "type": "array", "items": {"type": "string"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to add this user to groups."}, "404": {"description": "User not found."} } }, "delete": { "tags": ["users-api"], "summary": "Removes the user from one or more groups.", "description": "Removes the user from one or more groups.", "operationId": "usersIdRemoveGroupsUsingDELETE", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to remove role from", "required": true, "type": "string" }, { "in": "body", "name": "groups", "description": "The groups from which the user should be removed.", "required": true, "schema": { "type": "array", "items": {"type": "string"} } } ], "responses": { "200": { "description": "User successfully removed from all specified groups.", "schema": { "type": "array", "items": {"type": "string"} } }, "202": { "description": "User was successfully removed from some of the specified groups, but some may have failed. Check the return value for groups that the service was unable to remove.", "schema": { "type": "array", "items": {"type": "string"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "204": {"description": "No Content"}, "403": {"description": "Not authorized to remove this user from groups."}, "404": {"description": "User not found."} } } }, "/xapi/users/{username}/groups/{group}": { "put": { "tags": ["users-api"], "summary": "Adds a user to a group.", "description": "Assigns user to a group.", "operationId": "usersIdAddGroupUsingPUT", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to add to a group", "required": true, "type": "string" }, { "name": "group", "in": "path", "description": "The user's new group.", "required": true, "type": "string" } ], "responses": { "200": { "description": "User successfully added to group.", "schema": {"type": "boolean"} }, "201": {"description": "Created"}, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to assign this user to groups."}, "404": {"description": "User not found."} } }, "delete": { "tags": ["users-api"], "summary": "Removes a user from a group.", "description": "Removes a user from a group.", "operationId": "usersIdRemoveGroupUsingDELETE", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to remove from group", "required": true, "type": "string" }, { "name": "group", "in": "path", "description": "The group to remove the user from.", "required": true, "type": "string" } ], "responses": { "200": { "description": "User's group successfully removed.", "schema": {"type": "boolean"} }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "204": {"description": "No Content"}, "403": {"description": "Not authorized to remove this user from groups."}, "404": {"description": "User not found."} } } }, "/xapi/users/{username}/roles": { "get": { "tags": ["users-api"], "summary": "Returns the roles for the user with the specified user ID.", "description": "Returns a collection of the user's roles.", "operationId": "usersIdRolesGetUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [{ "name": "username", "in": "path", "description": "The ID of the user to retrieve the roles for.", "required": true, "type": "string" }], "responses": { "200": { "description": "User roles successfully retrieved.", "schema": {"$ref": "#/definitions/Collection"} }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to view this user."}, "404": {"description": "User not found."} } }, "put": { "tags": ["users-api"], "summary": "Adds one or more roles to a user.", "description": "Assigns one or more new roles to a user.", "operationId": "usersIdAddRolesUsingPUT", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to add a role to", "required": true, "type": "string" }, { "in": "body", "name": "roles", "description": "The user's new roles.", "required": true, "schema": { "type": "array", "items": {"type": "string"} } } ], "responses": { "200": { "description": "All specified user roles successfully added.", "schema": { "type": "array", "items": {"type": "string"} } }, "201": {"description": "Created"}, "202": { "description": "Some user roles successfully added, but some may have failed. Check the return value for roles that the service was unable to add.", "schema": { "type": "array", "items": {"type": "string"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to add roles to this user."}, "404": {"description": "User not found."} } }, "delete": { "tags": ["users-api"], "summary": "Removes one or more roles from a user.", "description": "Removes one or more new roles from a user.", "operationId": "usersIdRemoveRolesUsingDELETE", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to remove role from", "required": true, "type": "string" }, { "in": "body", "name": "roles", "description": "The roles to be removed.", "required": true, "schema": { "type": "array", "items": {"type": "string"} } } ], "responses": { "200": { "description": "All specified user roles successfully removed.", "schema": { "type": "array", "items": {"type": "string"} } }, "202": { "description": "Some user roles successfully removed, but some may have failed. Check the return value for roles that the service was unable to remove.", "schema": { "type": "array", "items": {"type": "string"} } }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "204": {"description": "No Content"}, "403": {"description": "Not authorized to remove roles from this user."}, "404": {"description": "User not found."} } } }, "/xapi/users/{username}/roles/{role}": { "put": { "tags": ["users-api"], "summary": "Adds a role to a user.", "description": "Assigns a new role to a user.", "operationId": "usersIdAddRoleUsingPUT", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to add a role to", "required": true, "type": "string" }, { "name": "role", "in": "path", "description": "The user's new role.", "required": true, "type": "string" } ], "responses": { "200": { "description": "User role successfully added.", "schema": {"type": "boolean"} }, "201": {"description": "Created"}, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to add a role to this user."}, "404": {"description": "User not found."} } }, "delete": { "tags": ["users-api"], "summary": "Remove a user's role.", "description": "Removes a user's role.", "operationId": "usersIdRemoveRoleUsingDELETE", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to delete a role from", "required": true, "type": "string" }, { "name": "role", "in": "path", "description": "The user role to delete.", "required": true, "type": "string" } ], "responses": { "200": { "description": "User role successfully removed.", "schema": {"type": "boolean"} }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "204": {"description": "No Content"}, "403": {"description": "Not authorized to remove a role from this user."}, "404": {"description": "User not found."} } } }, "/xapi/users/{username}/verified": {"get": { "tags": ["users-api"], "summary": "Returns whether the user with the specified user ID is verified.", "description": "Returns true or false based on whether the specified user is verified or not.", "operationId": "usersIdVerifiedGetUsingGET", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [{ "name": "username", "in": "path", "description": "The ID of the user to retrieve the verified status for.", "required": true, "type": "string" }], "responses": { "200": { "description": "User verified status successfully retrieved.", "schema": {"type": "boolean"} }, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to view this user."}, "404": {"description": "User not found."} } }}, "/xapi/users/{username}/verified/{flag}": {"put": { "tags": ["users-api"], "summary": "Sets the user's verified state.", "description": "Sets the verified state of the user with the specified user ID to the value of the flag parameter.", "operationId": "usersIdVerifiedFlagPutUsingPUT", "consumes": ["application/json"], "produces": ["application/json"], "parameters": [ { "name": "username", "in": "path", "description": "ID of the user to fetch", "required": true, "type": "string" }, { "name": "flag", "in": "path", "description": "The value to set for the verified status.", "required": true, "type": "boolean" } ], "responses": { "200": { "description": "User verified status successfully set.", "schema": {"type": "boolean"} }, "201": {"description": "Created"}, "401": {"description": "Must be authenticated to access the XNAT REST API."}, "500": {"description": "An unexpected error occurred."}, "403": {"description": "Not authorized to verify or un-verify this user."}, "404": {"description": "User not found."} } }}, } }



  • No labels