src/main/resources/Documentation/rest-api-config.md - plugins/serviceuser - Git at Google

 @PLUGIN@ - /config/ REST API
 ============================

 This page describes the REST endpoints that are added by the @PLUGIN@
 plugin.

 Please also take note of the general information on the
 [REST API](../../../Documentation/rest-api.html).

 <a id="project-endpoints"> Service User Endpoints
 -------------------------------------------------

 ### <a id="create-service-user"> Create Service User
 _POST /config/server/@PLUGIN@~serviceusers/\{username\}_

 Creates a service user.

 The public SSH key for creating the service user must be specified in
 the request body as a [ServiceUserInput](#service-user-input) entity.

 Caller must be a member of a group that is granted the 'Create Service
 User' capability (provided by this plugin) or the 'Administrate Server'
 capability.

 #### Request

 ```
   POST /config/server/@PLUGIN@~serviceusers/JenkinsVoter HTTP/1.0
   Content-Type: application/json;charset=UTF-8

   {
     "ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw=="
   }
 ```

 As response a [ServiceUserInfo](#service-user-info) entity is returned
 that describes the created account.

 #### Response

 ```
   HTTP/1.1 201 Created
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   {
     "created_by": "jdoe",
     "created_at": "Thu, 21 Nov 2013 15:00:55 +0100",
     "_account_id": 1000195,
     "name": "JenkinsVoter",
     "avatars": []
   }
 ```

 ### <a id="get-service-user"> Get Service User
 _GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)_

 Gets a service user.

 In order to be able to see a service user the caller must be

 * a member of the owner group,
 * the creator of the service user if no owner group is assigned or
 * a member of a group that is granted the 'Administrate Server' capability.

 #### Request

 ```
   GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter HTTP/1.0
 ```

 As response a [ServiceUserInfo](#service-user-info) entity is returned
 that describes the service user.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   {
     "created_by": "jdoe",
     "created_at": "Thu, 21 Nov 2013 15:00:55 +0100",
     "_account_id": 1000195,
     "name": "JenkinsVoter",
     "username": "JenkinsVoter",
     "avatars": []
   }
 ```

 ### <a id="list-service-users"> List Service Users
 GET /config/server/@PLUGIN@~serviceusers/_

 Lists service users.

 In order to be able to see a service user the caller must be

 * a member of the owner group,
 * the creator of the service user if no owner group is assigned or
 * a member of a group that is granted the 'Administrate Server' capability.

 #### Request

 ```
   GET /config/server/@PLUGIN@~serviceusers/ HTTP/1.0
 ```

 As response a map is returned that maps the username to a
 [ServiceUserInfo](#service-user-info) entity. The username in
 ServiceUserInfo is not set since it is already available as map key.

 #### Response

 ```
   HTTP/1.1 201 Created
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   {
     "GlobalVerifier": {
       "created_by": "jdoe",
       "created_at": "Mon, 27 Jan 2014 21:00:12 +0100",
       "_account_id": 1000107,
       "name": "GlobalVerifier",
       "avatars": []
     },
     "JenkinsVoter": {
       "created_by": "jdoe",
       "created_at": "Thu, 21 Nov 2013 15:00:55 +0100",
       "_account_id": 1000195,
       "name": "JenkinsVoter",
       "avatars": []
     }
   }
 ```

 ### <a id="list-ssh-keys"> List SSH keys
 GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/sshkeys/_

 Lists the SSH keys of a service user.

 #### Request

 ```
   GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/sshkeys/ HTTP/1.0
 ```

 As response a list of [SshKeyInfo](../../../Documentation/rest-api-accounts.html#ssh-key-info)
 entities is returned.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   [
     {
       "seq": 1,
       "ssh_public_key": "ssh-rsa AAAAB3NzaC1...",
       "encoded_key": "AAAAB3NzaC1...",
       "algorithm": "ssh-rsa",
       "comment": "jenkins.voter@gerrit.com",
       "valid": true
     }
   ]
 ```

 ### <a id="get-ssh-key"> Get SSH key
 GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/sshkeys/[\{ssh-key-id\}](../../../Documentation/rest-api-accounts.html#ssh-key-id)_

 Gets an SSH key of a service user.

 #### Request

 ```
   GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/sshkeys/1 HTTP/1.0
 ```

 As response an [SshKeyInfo](../../../Documentation/rest-api-accounts.html#ssh-key-info)
 entity is returned.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   {
     "seq": 1,
     "ssh_public_key": "ssh-rsa AAAAB3NzaC1...",
     "encoded_key": "AAAAB3NzaC1...",
     "algorithm": "ssh-rsa",
     "comment": "jenkins.voter@gerrit.com",
     "valid": true
   }
 ```

 ### <a id="add-ssh-key"> Add SSH key
 POST /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/sshkeys_

 Adds an SSH key for a service user.

 #### Request

 ```
   POST /config/server/@PLUGIN@~serviceusers/JenkinsVoter/sshkeys HTTP/1.0
   Content-Type: plain/text

   AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d
 ```

 As response an [SshKeyInfo](../../../Documentation/rest-api-accounts.html#ssh-key-info)
 entity is returned that describes the new SSH key.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   [
     {
       "seq": 2,
       "ssh_public_key": "ssh-rsa AAAAB1NzaA2...",
       "encoded_key": "AAAAB1NzaA2...",
       "algorithm": "ssh-rsa",
       "comment": "jenkins.voter@gerrit.com",
       "valid": true
     }
   ]
 ```

 ### <a id="delete-ssh-key"> Delete SSH key
 DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/sshkeys/[\{ssh-key-id\}](../../../Documentation/rest-api-accounts.html#ssh-key-id)_

 Deletes an SSH key of a service user.

 #### Request

 ```
   DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/sshkeys/2 HTTP/1.0
 ```

 #### Response

 ```
   HTTP/1.1 204 No Content
 ```

 ### <a id="get-full-name"> Get Full Name
 GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/name_

 Retrieves the full name of a service user.

 #### Request

 ```
   GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/name HTTP/1.0
 ```

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   "Jenkins Voter"
 ```

 If the service user does not have a name an empty string is returned.

 ### <a id="set-full-name"> Set Full Name
 PUT /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/name_

 Sets the full name of a service user.

 The new full name must be provided in the request body inside a
 [AccountNameInput](../../../Documentation/rest-api-accounts.html#account-name-input)
 entity.

 #### Request

 ```
   PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/name HTTP/1.0
   Content-Type: application/json;charset=UTF-8

   {
     "name": "Jenkins Voter"
   }
 ```

 As response the new full name is returned.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   "Jenkins Voter"
 ```

 If the name was deleted the response is "`204 No Content`".

 Some realms may not allow to modify the full name. In this case the
 request is rejected with "`405 Method Not Allowed`".

 ### <a id="delete-full-name"> Delete Full Name
 DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/name_

 Deletes the full name of a service user.

 #### Request

 ```
   DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/name HTTP/1.0
 ```

 As response the new full name is returned.

 #### Response

 ```
   HTTP/1.1 204 No Content
 ```

 Some realms may not allow to modify the full name. In this case the
 request is rejected with "`405 Method Not Allowed`".

 ### <a id="get-email"> Get Email
 GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/email_

 Retrieves the (preferred) email of a service user.

 #### Request

 ```
   GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/email HTTP/1.0
 ```

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   "jenkins.voter@gerrit.com"
 ```

 If the service user does not have an email address an empty string is returned.

 ### <a id="set-email"> Set Email
 PUT /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/email_

 Sets the (preferred) email of a service user.

 The new email must be provided in the request body inside a
 [EmailInput](#email-input) entity.

 #### Request

 ```
   PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/email HTTP/1.0
   Content-Type: application/json;charset=UTF-8

   {
     "email": "jenkins.voter@gerrit.com"
   }
 ```

 As response the new email is returned.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   "jenkins.voter@gerrit.com"
 ```

 If the email was deleted the response is "`204 No Content`".

 Some realms may not allow to modify the email. In this case the
 request is rejected with "`405 Method Not Allowed`".

 ### <a id="delete-email"> Delete Email
 DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/email_

 Deletes the email of a service user.

 #### Request

 ```
   DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/email HTTP/1.0
 ```

 As response "`204 No Content`" is returned.

 #### Response

 ```
   HTTP/1.1 204 No Content
 ```

 Some realms may not allow to modify the email. In this case the
 request is rejected with "`405 Method Not Allowed`".

 ### <a id="set-http-password"> Set/Generate HTTP password
 PUT
 /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/password.http_

 Sets/Generates an HTTP password for a service user.

 The options for setting/generating the HTTP password must be provided
 in the request body inside a [HttpPasswordInput](#http-password-input)
 entity.

 #### Request

 ```
   PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/password.http HTTP/1.0
   Content-Type: application/json;charset=UTF-8

   {
     "generate": true
   }
 ```

 As response the new HTTP password is returned.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   "6A5zoF7Bf2fMggf4R6pO3Bzgchnwl6oBI8+yA3YJUA"
 ```

 If the HTTP password was deleted the response is "`204 No Content`".


 ### <a id="delete-http-password"> Delete HTTP password
 DELETE
 /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/password.http

 Clears the HTTP password of a service user.

 #### Request

 ```
   DELETE
   /config/server/@PLUGIN@~serviceusers/JenkinsVoter/password.http HTTP/1.0
 ```

 As response "`204 No Content`" is returned.

 #### Response

 ```
   HTTP/1.1 204 No Content
 ```

 ### <a id="get-active"> Get Active
 GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/active_

 Checks if a service user is active.

 #### Request

 ```
   GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/active HTTP/1.0
 ```

 If the service user is active the string `ok` is returned.

 #### Response

 ```
   HTTP/1.1 200 OK

   ok
 ```

 If the service user is inactive the response is `204 No Content`.

 ### <a id="set-active"> Set Active
 PUT /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/active_

 Sets the service user state to active.

 #### Request

 ```
   PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/active HTTP/1.0
 ```

 #### Response

 ```
   HTTP/1.1 201 Created
 ```

 If the service user was already active the response is `200 OK`.

 ### <a id="delete-active"> Delete Active
 DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/active_

 Sets the service user state to inactive.

 #### Request

 ```
   DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/active HTTP/1.0
 ```

 #### Response

 ```
   HTTP/1.1 204 No Content
 ```

 ### <a id="get-owner"> Get Owner
 GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/owner_

 Retrieves the owner group of the service user.

 #### Request

 ```
   GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/owner HTTP/1.0
 ```

 The owner group is returned as a
 [GroupInfo](../../../Documentation/rest-api-groups.html#group-info)
 entity.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Type: application/json;charset=UTF-8

   {
     "kind": "gerritcodereview#group",
     "url": "#/admin/groups/uuid-2a97064e13ebc5c64b963d09a66219e539854226",
     "options": {},
     "description": "Jenkins Administrators",
     "group_id": 10,
     "owner": "JenkinsAdmins",
     "owner_id": "2a97064e13ebc5c64b963d09a66219e539854226",
     "id": "2a97064e13ebc5c64b963d09a66219e539854226",
     "name": "JenkinsAdmins"
   }
 ```

 If no owner group for the service user is set the response is `200 OK`
 without any content in the request body.

 If an owner group is set but the group is not visible to the caller or
 doesn't exist anymore the response is `404 Not Found`.

 ### <a id="set-owner"> Set Owner
 PUT /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/owner_

 Sets the owner group for a service user.

 The owner group must be specified in the request body as a
 [OwnerInput](#owner-input) entity.

 #### Request

 ```
   PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/owner HTTP/1.0
   Content-Type: application/json;charset=UTF-8

   {
     "group": "JenkinsAdmins"
   }
 ```

 As response the new owner group is returned as a
 [GroupInfo](../../../Documentation/rest-api-groups.html#group-info)
 entity.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Type: application/json;charset=UTF-8

   {
     "kind": "gerritcodereview#group",
     "url": "#/admin/groups/uuid-2a97064e13ebc5c64b963d09a66219e539854226",
     "options": {},
     "description": "Jenkins Administrators",
     "group_id": 10,
     "owner": "JenkinsAdmins",
     "owner_id": "2a97064e13ebc5c64b963d09a66219e539854226",
     "id": "2a97064e13ebc5c64b963d09a66219e539854226",
     "name": "JenkinsAdmins"
   }
 ```

 If the service user didn't have an owner group before the response is
 `201 Created`.

 If the owner group of the service user is deleted the response is
 `204 No Content`.

 ### <a id="delete-owner"> Delete Owner
 DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/owner_

 Delete the owner group of a service user.

 #### Request

 ```
   DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/owner HTTP/1.0
 ```

 #### Response

 ```
   HTTP/1.1 204 No Content
 ```

 ### <a id="get-config"> Get Config
 _GET /config/server/@PLUGIN@~config_

 Gets the configuration of the @PLUGIN@ plugin.

 #### Request

 ```
   GET /config/server/@PLUGIN@~config HTTP/1.0
 ```

 As response a [ConfigInfo](#config-info) entity is returned that
 contains the configuration.

 #### Response

 ```
   HTTP/1.1 200 OK
   Content-Disposition: attachment
   Content-Type: application/json;charset=UTF-8

   )]}'
   {
     "on_success": "Don\u0027t forget to assign \u003ca href\u003d\"Documentation/access-control.html\"\u003eaccess rights\u003c/a\u003e to the service user.",
     "create_notes": true
   }
 ```

 ### <a id="put-config"> Put Config
 _PUT /config/server/@PLUGIN@~config_

 Sets the configuration of the @PLUGIN@ plugin.

 The new configuration must be specified as a [ConfigInput](#config-input)
 entity in the request body. Not setting a parameter leaves the parameter
 unchanged.

 #### Request

 ```
   PUT /config/server/@PLUGIN@~config HTTP/1.0
   Content-Type: application/json;charset=UTF-8

   {
     "info": "Please find more information about service users in the <a href\"wiki.html\">wiki</a>."
   }
 ```


 <a id="json-entities">JSON Entities
 -----------------------------------

 ### <a id="config-info"></a>ConfigInfo

 The `ConfigInfo` entity contains the configuration of the @PLUGIN@
 plugin.

 * _info_: HTML formatted message that should be displayed on the
   service user creation screen.
 * _on\_success_: Message that should be displayed after a service user
   was successfully created.
 * _allow\_email_: Whether it is allowed to provide an email address for
   a service user (not set if `false`).
 * _allow\_http\_password_: Whether it is allowed to generate an HTTP
   password for a service user (not set if `false`).
 * _create\_notes_: Whether commits of a service user should be
   annotated by a Git note that contains information about the current
   owners of the service user (not set if `false`).
 * _create\_notes\_async_: Whether the Git notes on commits that are
   pushed by a service user should be created asynchronously (not set if
   `false`).
 * _blocked\_names_: List of usernames which are forbidden to be used as
   name for a service user. The blocked usernames are case insensitive.
 * _groups_: Map of groups to which newly created service users are
   automatically added. The map maps the group name to a
   [GroupInfo](../../../Documentation/rest-api-groups.html#group-info)
   entity. The `name` field in the GroupInfo entities is not set since
   the names are already available as map keys.

 ### <a id="config-input"></a>ConfigInput

 The `ConfigInput` entity contains updates for the configuration of the
 @PLUGIN@ plugin.

 * _info_: HTML formatted message that should be displayed on the
   service user creation screen.
 * _on\_success_: Message that should be displayed after a service user
   was successfully created.
 * _allow\_email_: Whether it is allowed to provide an email address for
   a service user (not set if `false`).
 * _allow\_http\_password_: Whether it is allowed to generate an HTTP
   password for a service user (not set if `false`).
 * _allow\_owner_: Whether it is allowed to set an owner group for a
   service user (not set if `false`).
 * _create\_notes_: Whether commits of a service user should be
   annotated by a Git note that contains information about the current
   owners of the service user (not set if `false`).
 * _create\_notes\_async_: Whether the Git notes on commits that are
   pushed by a service user should be created asynchronously (not set if
   `false`).
 * _blocked\_names_: List of usernames which are forbidden to be used as
   name for a service user. The blocked usernames are case insensitive.
 * _groups_: List of names of internal groups to which newly created
   service users should be automatically added.

 ### <a id="email-input"></a>EmailInput

 The `EmailInput` entity contains a new email address.

 * _email_: The new email address.

 ### <a id="http-password-input"></a>HttpPasswordInput

 The `HttpPasswordInput` entity contains information for
 setting/generating an HTTP password.

 * _generate_: Whether a new HTTP password should be generated.
 * _http\_password_: The new HTTP password.

 ### <a id="owner-input"></a>OwnerInput

 The `OwnerInput` entity contains a group that should own a service user.

 * _group_: An internal Gerrit group. This can be the UUID of the group,
   the legacy numeric ID of the group or the name of the group if it is
   unique.

 ### <a id="service-user-info"></a>ServiceUserInfo

 The `ServiceUserInfo` entity contains information about a service user.
 It has the same fields as a detailed
 [AccountInfo](../../../Documentation/rest-api-accounts.html#account-info)
 and in addition the following fields:

 * _created\_by_: The user that created this service user as a detailed
   [AccountInfo](../../../Documentation/rest-api-accounts.html#account-info)
   entity.
 * _created\_at_: The date when the service user was created in the
   format 'EEE, dd MMM yyyy HH:mm:ss Z'.
 * _inactive_: Whether the account state of the service user is
   inactive. Not set if the account is active.
 * _owner_: The owner group of the service user as a
   [GroupInfo](../../../Documentation/rest-api-groups.html#group-info)
   entity. Not set if no owner group is assigned.

 ### <a id="service-user-input"></a>ServiceUserInput

 The `ServiceUserInput` entity contains options for creating a service
 user.

 * _ssh\_key_: Content of the public SSH key to load into the account's keyring.

 SEE ALSO
 --------

 * [Config related REST endpoints](../../../Documentation/rest-api-config.html)

 GERRIT
 ------
 Part of [Gerrit Code Review](../../../Documentation/index.html)
	@PLUGIN@ - /config/ REST API
	============================

	This page describes the REST endpoints that are added by the @PLUGIN@
	plugin.

	Please also take note of the general information on the
	[REST API](../../../Documentation/rest-api.html).

	<a id="project-endpoints"> Service User Endpoints
	-------------------------------------------------

	### <a id="create-service-user"> Create Service User
	_POST /config/server/@PLUGIN@~serviceusers/\{username\}_

	Creates a service user.

	The public SSH key for creating the service user must be specified in
	the request body as a [ServiceUserInput](#service-user-input) entity.

	Caller must be a member of a group that is granted the 'Create Service
	User' capability (provided by this plugin) or the 'Administrate Server'
	capability.

	#### Request

	```
	POST /config/server/@PLUGIN@~serviceusers/JenkinsVoter HTTP/1.0
	Content-Type: application/json;charset=UTF-8

	{
	"ssh_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw=="
	}
	```

	As response a [ServiceUserInfo](#service-user-info) entity is returned
	that describes the created account.

	#### Response

	```
	HTTP/1.1 201 Created
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	{
	"created_by": "jdoe",
	"created_at": "Thu, 21 Nov 2013 15:00:55 +0100",
	"_account_id": 1000195,
	"name": "JenkinsVoter",
	"avatars": []
	}
	```

	### <a id="get-service-user"> Get Service User
	_GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)_

	Gets a service user.

	In order to be able to see a service user the caller must be

	* a member of the owner group,
	* the creator of the service user if no owner group is assigned or
	* a member of a group that is granted the 'Administrate Server' capability.

	#### Request

	```
	GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter HTTP/1.0
	```

	As response a [ServiceUserInfo](#service-user-info) entity is returned
	that describes the service user.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	{
	"created_by": "jdoe",
	"created_at": "Thu, 21 Nov 2013 15:00:55 +0100",
	"_account_id": 1000195,
	"name": "JenkinsVoter",
	"username": "JenkinsVoter",
	"avatars": []
	}
	```

	### <a id="list-service-users"> List Service Users
	GET /config/server/@PLUGIN@~serviceusers/_

	Lists service users.

	In order to be able to see a service user the caller must be

	* a member of the owner group,
	* the creator of the service user if no owner group is assigned or
	* a member of a group that is granted the 'Administrate Server' capability.

	#### Request

	```
	GET /config/server/@PLUGIN@~serviceusers/ HTTP/1.0
	```

	As response a map is returned that maps the username to a
	[ServiceUserInfo](#service-user-info) entity. The username in
	ServiceUserInfo is not set since it is already available as map key.

	#### Response

	```
	HTTP/1.1 201 Created
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	{
	"GlobalVerifier": {
	"created_by": "jdoe",
	"created_at": "Mon, 27 Jan 2014 21:00:12 +0100",
	"_account_id": 1000107,
	"name": "GlobalVerifier",
	"avatars": []
	},
	"JenkinsVoter": {
	"created_by": "jdoe",
	"created_at": "Thu, 21 Nov 2013 15:00:55 +0100",
	"_account_id": 1000195,
	"name": "JenkinsVoter",
	"avatars": []
	}
	}
	```

	### <a id="list-ssh-keys"> List SSH keys
	GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/sshkeys/_

	Lists the SSH keys of a service user.

	#### Request

	```
	GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/sshkeys/ HTTP/1.0
	```

	As response a list of [SshKeyInfo](../../../Documentation/rest-api-accounts.html#ssh-key-info)
	entities is returned.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	[
	{
	"seq": 1,
	"ssh_public_key": "ssh-rsa AAAAB3NzaC1...",
	"encoded_key": "AAAAB3NzaC1...",
	"algorithm": "ssh-rsa",
	"comment": "jenkins.voter@gerrit.com",
	"valid": true
	}
	]
	```

	### <a id="get-ssh-key"> Get SSH key
	GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/sshkeys/[\{ssh-key-id\}](../../../Documentation/rest-api-accounts.html#ssh-key-id)_

	Gets an SSH key of a service user.

	#### Request

	```
	GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/sshkeys/1 HTTP/1.0
	```

	As response an [SshKeyInfo](../../../Documentation/rest-api-accounts.html#ssh-key-info)
	entity is returned.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	{
	"seq": 1,
	"ssh_public_key": "ssh-rsa AAAAB3NzaC1...",
	"encoded_key": "AAAAB3NzaC1...",
	"algorithm": "ssh-rsa",
	"comment": "jenkins.voter@gerrit.com",
	"valid": true
	}
	```

	### <a id="add-ssh-key"> Add SSH key
	POST /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/sshkeys_

	Adds an SSH key for a service user.

	#### Request

	```
	POST /config/server/@PLUGIN@~serviceusers/JenkinsVoter/sshkeys HTTP/1.0
	Content-Type: plain/text

	AAAAB3NzaC1yc2EAAAABIwAAAQEA0T...YImydZAw\u003d\u003d
	```

	As response an [SshKeyInfo](../../../Documentation/rest-api-accounts.html#ssh-key-info)
	entity is returned that describes the new SSH key.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	[
	{
	"seq": 2,
	"ssh_public_key": "ssh-rsa AAAAB1NzaA2...",
	"encoded_key": "AAAAB1NzaA2...",
	"algorithm": "ssh-rsa",
	"comment": "jenkins.voter@gerrit.com",
	"valid": true
	}
	]
	```

	### <a id="delete-ssh-key"> Delete SSH key
	DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/sshkeys/[\{ssh-key-id\}](../../../Documentation/rest-api-accounts.html#ssh-key-id)_

	Deletes an SSH key of a service user.

	#### Request

	```
	DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/sshkeys/2 HTTP/1.0
	```

	#### Response

	```
	HTTP/1.1 204 No Content
	```

	### <a id="get-full-name"> Get Full Name
	GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/name_

	Retrieves the full name of a service user.

	#### Request

	```
	GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/name HTTP/1.0
	```

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	"Jenkins Voter"
	```

	If the service user does not have a name an empty string is returned.

	### <a id="set-full-name"> Set Full Name
	PUT /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/name_

	Sets the full name of a service user.

	The new full name must be provided in the request body inside a
	[AccountNameInput](../../../Documentation/rest-api-accounts.html#account-name-input)
	entity.

	#### Request

	```
	PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/name HTTP/1.0
	Content-Type: application/json;charset=UTF-8

	{
	"name": "Jenkins Voter"
	}
	```

	As response the new full name is returned.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	"Jenkins Voter"
	```

	If the name was deleted the response is "`204 No Content`".

	Some realms may not allow to modify the full name. In this case the
	request is rejected with "`405 Method Not Allowed`".

	### <a id="delete-full-name"> Delete Full Name
	DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/name_

	Deletes the full name of a service user.

	#### Request

	```
	DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/name HTTP/1.0
	```

	As response the new full name is returned.

	#### Response

	```
	HTTP/1.1 204 No Content
	```

	Some realms may not allow to modify the full name. In this case the
	request is rejected with "`405 Method Not Allowed`".

	### <a id="get-email"> Get Email
	GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/email_

	Retrieves the (preferred) email of a service user.

	#### Request

	```
	GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/email HTTP/1.0
	```

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	"jenkins.voter@gerrit.com"
	```

	If the service user does not have an email address an empty string is returned.

	### <a id="set-email"> Set Email
	PUT /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/email_

	Sets the (preferred) email of a service user.

	The new email must be provided in the request body inside a
	[EmailInput](#email-input) entity.

	#### Request

	```
	PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/email HTTP/1.0
	Content-Type: application/json;charset=UTF-8

	{
	"email": "jenkins.voter@gerrit.com"
	}
	```

	As response the new email is returned.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	"jenkins.voter@gerrit.com"
	```

	If the email was deleted the response is "`204 No Content`".

	Some realms may not allow to modify the email. In this case the
	request is rejected with "`405 Method Not Allowed`".

	### <a id="delete-email"> Delete Email
	DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/email_

	Deletes the email of a service user.

	#### Request

	```
	DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/email HTTP/1.0
	```

	As response "`204 No Content`" is returned.

	#### Response

	```
	HTTP/1.1 204 No Content
	```

	Some realms may not allow to modify the email. In this case the
	request is rejected with "`405 Method Not Allowed`".

	### <a id="set-http-password"> Set/Generate HTTP password
	PUT
	/config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/password.http_

	Sets/Generates an HTTP password for a service user.

	The options for setting/generating the HTTP password must be provided
	in the request body inside a [HttpPasswordInput](#http-password-input)
	entity.

	#### Request

	```
	PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/password.http HTTP/1.0
	Content-Type: application/json;charset=UTF-8

	{
	"generate": true
	}
	```

	As response the new HTTP password is returned.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	"6A5zoF7Bf2fMggf4R6pO3Bzgchnwl6oBI8+yA3YJUA"
	```

	If the HTTP password was deleted the response is "`204 No Content`".


	### <a id="delete-http-password"> Delete HTTP password
	DELETE
	/config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/password.http

	Clears the HTTP password of a service user.

	#### Request

	```
	DELETE
	/config/server/@PLUGIN@~serviceusers/JenkinsVoter/password.http HTTP/1.0
	```

	As response "`204 No Content`" is returned.

	#### Response

	```
	HTTP/1.1 204 No Content
	```

	### <a id="get-active"> Get Active
	GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/active_

	Checks if a service user is active.

	#### Request

	```
	GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/active HTTP/1.0
	```

	If the service user is active the string `ok` is returned.

	#### Response

	```
	HTTP/1.1 200 OK

	ok
	```

	If the service user is inactive the response is `204 No Content`.

	### <a id="set-active"> Set Active
	PUT /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/active_

	Sets the service user state to active.

	#### Request

	```
	PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/active HTTP/1.0
	```

	#### Response

	```
	HTTP/1.1 201 Created
	```

	If the service user was already active the response is `200 OK`.

	### <a id="delete-active"> Delete Active
	DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/active_

	Sets the service user state to inactive.

	#### Request

	```
	DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/active HTTP/1.0
	```

	#### Response

	```
	HTTP/1.1 204 No Content
	```

	### <a id="get-owner"> Get Owner
	GET /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/owner_

	Retrieves the owner group of the service user.

	#### Request

	```
	GET /config/server/@PLUGIN@~serviceusers/JenkinsVoter/owner HTTP/1.0
	```

	The owner group is returned as a
	[GroupInfo](../../../Documentation/rest-api-groups.html#group-info)
	entity.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Type: application/json;charset=UTF-8

	{
	"kind": "gerritcodereview#group",
	"url": "#/admin/groups/uuid-2a97064e13ebc5c64b963d09a66219e539854226",
	"options": {},
	"description": "Jenkins Administrators",
	"group_id": 10,
	"owner": "JenkinsAdmins",
	"owner_id": "2a97064e13ebc5c64b963d09a66219e539854226",
	"id": "2a97064e13ebc5c64b963d09a66219e539854226",
	"name": "JenkinsAdmins"
	}
	```

	If no owner group for the service user is set the response is `200 OK`
	without any content in the request body.

	If an owner group is set but the group is not visible to the caller or
	doesn't exist anymore the response is `404 Not Found`.

	### <a id="set-owner"> Set Owner
	PUT /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/owner_

	Sets the owner group for a service user.

	The owner group must be specified in the request body as a
	[OwnerInput](#owner-input) entity.

	#### Request

	```
	PUT /config/server/@PLUGIN@~serviceusers/JenkinsVoter/owner HTTP/1.0
	Content-Type: application/json;charset=UTF-8

	{
	"group": "JenkinsAdmins"
	}
	```

	As response the new owner group is returned as a
	[GroupInfo](../../../Documentation/rest-api-groups.html#group-info)
	entity.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Type: application/json;charset=UTF-8

	{
	"kind": "gerritcodereview#group",
	"url": "#/admin/groups/uuid-2a97064e13ebc5c64b963d09a66219e539854226",
	"options": {},
	"description": "Jenkins Administrators",
	"group_id": 10,
	"owner": "JenkinsAdmins",
	"owner_id": "2a97064e13ebc5c64b963d09a66219e539854226",
	"id": "2a97064e13ebc5c64b963d09a66219e539854226",
	"name": "JenkinsAdmins"
	}
	```

	If the service user didn't have an owner group before the response is
	`201 Created`.

	If the owner group of the service user is deleted the response is
	`204 No Content`.

	### <a id="delete-owner"> Delete Owner
	DELETE /config/server/@PLUGIN@~serviceusers/[\{account-id\}](../../../Documentation/rest-api-accounts.html#account-id)/owner_

	Delete the owner group of a service user.

	#### Request

	```
	DELETE /config/server/@PLUGIN@~serviceusers/JenkinsVoter/owner HTTP/1.0
	```

	#### Response

	```
	HTTP/1.1 204 No Content
	```

	### <a id="get-config"> Get Config
	_GET /config/server/@PLUGIN@~config_

	Gets the configuration of the @PLUGIN@ plugin.

	#### Request

	```
	GET /config/server/@PLUGIN@~config HTTP/1.0
	```

	As response a [ConfigInfo](#config-info) entity is returned that
	contains the configuration.

	#### Response

	```
	HTTP/1.1 200 OK
	Content-Disposition: attachment
	Content-Type: application/json;charset=UTF-8

	)]}'
	{
	"on_success": "Don\u0027t forget to assign \u003ca href\u003d\"Documentation/access-control.html\"\u003eaccess rights\u003c/a\u003e to the service user.",
	"create_notes": true
	}
	```

	### <a id="put-config"> Put Config
	_PUT /config/server/@PLUGIN@~config_

	Sets the configuration of the @PLUGIN@ plugin.

	The new configuration must be specified as a [ConfigInput](#config-input)
	entity in the request body. Not setting a parameter leaves the parameter
	unchanged.

	#### Request

	```
	PUT /config/server/@PLUGIN@~config HTTP/1.0
	Content-Type: application/json;charset=UTF-8

	{
	"info": "Please find more information about service users in the <a href\"wiki.html\">wiki</a>."
	}
	```


	<a id="json-entities">JSON Entities
	-----------------------------------

	### <a id="config-info"></a>ConfigInfo

	The `ConfigInfo` entity contains the configuration of the @PLUGIN@
	plugin.

	* _info_: HTML formatted message that should be displayed on the
	service user creation screen.
	* _on\_success_: Message that should be displayed after a service user
	was successfully created.
	* _allow\_email_: Whether it is allowed to provide an email address for
	a service user (not set if `false`).
	* _allow\_http\_password_: Whether it is allowed to generate an HTTP
	password for a service user (not set if `false`).
	* _create\_notes_: Whether commits of a service user should be
	annotated by a Git note that contains information about the current
	owners of the service user (not set if `false`).
	* _create\_notes\_async_: Whether the Git notes on commits that are
	pushed by a service user should be created asynchronously (not set if
	`false`).
	* _blocked\_names_: List of usernames which are forbidden to be used as
	name for a service user. The blocked usernames are case insensitive.
	* _groups_: Map of groups to which newly created service users are
	automatically added. The map maps the group name to a
	[GroupInfo](../../../Documentation/rest-api-groups.html#group-info)
	entity. The `name` field in the GroupInfo entities is not set since
	the names are already available as map keys.

	### <a id="config-input"></a>ConfigInput

	The `ConfigInput` entity contains updates for the configuration of the
	@PLUGIN@ plugin.

	* _info_: HTML formatted message that should be displayed on the
	service user creation screen.
	* _on\_success_: Message that should be displayed after a service user
	was successfully created.
	* _allow\_email_: Whether it is allowed to provide an email address for
	a service user (not set if `false`).
	* _allow\_http\_password_: Whether it is allowed to generate an HTTP
	password for a service user (not set if `false`).
	* _allow\_owner_: Whether it is allowed to set an owner group for a
	service user (not set if `false`).
	* _create\_notes_: Whether commits of a service user should be
	annotated by a Git note that contains information about the current
	owners of the service user (not set if `false`).
	* _create\_notes\_async_: Whether the Git notes on commits that are
	pushed by a service user should be created asynchronously (not set if
	`false`).
	* _blocked\_names_: List of usernames which are forbidden to be used as
	name for a service user. The blocked usernames are case insensitive.
	* _groups_: List of names of internal groups to which newly created
	service users should be automatically added.

	### <a id="email-input"></a>EmailInput

	The `EmailInput` entity contains a new email address.

	* _email_: The new email address.

	### <a id="http-password-input"></a>HttpPasswordInput

	The `HttpPasswordInput` entity contains information for
	setting/generating an HTTP password.

	* _generate_: Whether a new HTTP password should be generated.
	* _http\_password_: The new HTTP password.

	### <a id="owner-input"></a>OwnerInput

	The `OwnerInput` entity contains a group that should own a service user.

	* _group_: An internal Gerrit group. This can be the UUID of the group,
	the legacy numeric ID of the group or the name of the group if it is
	unique.

	### <a id="service-user-info"></a>ServiceUserInfo

	The `ServiceUserInfo` entity contains information about a service user.
	It has the same fields as a detailed
	[AccountInfo](../../../Documentation/rest-api-accounts.html#account-info)
	and in addition the following fields:

	* _created\_by_: The user that created this service user as a detailed
	[AccountInfo](../../../Documentation/rest-api-accounts.html#account-info)
	entity.
	* _created\_at_: The date when the service user was created in the
	format 'EEE, dd MMM yyyy HH:mm:ss Z'.
	* _inactive_: Whether the account state of the service user is
	inactive. Not set if the account is active.
	* _owner_: The owner group of the service user as a
	[GroupInfo](../../../Documentation/rest-api-groups.html#group-info)
	entity. Not set if no owner group is assigned.

	### <a id="service-user-input"></a>ServiceUserInput

	The `ServiceUserInput` entity contains options for creating a service
	user.

	* _ssh\_key_: Content of the public SSH key to load into the account's keyring.

	SEE ALSO
	--------

	* [Config related REST endpoints](../../../Documentation/rest-api-config.html)

	GERRIT
	------
	Part of [Gerrit Code Review](../../../Documentation/index.html)