@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.

Service User Endpoints

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 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 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": []
  }

Get Service User

GET /config/server/@PLUGIN@~serviceusers/{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 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": []
  }

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 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": []
    }
  }

List SSH keys

GET /config/server/@PLUGIN@~serviceusers/{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 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
    }
  ]

Get SSH key

GET /config/server/@PLUGIN@~serviceusers/{account-id}/sshkeys/{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 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
  }

Add SSH key

POST /config/server/@PLUGIN@~serviceusers/{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 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
    }
  ]

Delete SSH key

DELETE /config/server/@PLUGIN@~serviceusers/{account-id}/sshkeys/{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

Get Full Name

GET /config/server/@PLUGIN@~serviceusers/{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.

Set Full Name

PUT /config/server/@PLUGIN@~serviceusers/{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 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”.

Delete Full Name

DELETE /config/server/@PLUGIN@~serviceusers/{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”.

Get Email

GET /config/server/@PLUGIN@~serviceusers/{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.

Set Email

PUT /config/server/@PLUGIN@~serviceusers/{account-id}/email_

Sets the (preferred) email of a service user.

The new email must be provided in the request body inside a EmailInput 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”.

Delete Email

DELETE /config/server/@PLUGIN@~serviceusers/{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”.

Set/Generate HTTP password

PUT /config/server/@PLUGIN@~serviceusers/{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 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”.

Delete HTTP password

DELETE /config/server/@PLUGIN@~serviceusers/{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

Get Active

GET /config/server/@PLUGIN@~serviceusers/{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.

Set Active

PUT /config/server/@PLUGIN@~serviceusers/{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.

Delete Active

DELETE /config/server/@PLUGIN@~serviceusers/{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

Get Owner

GET /config/server/@PLUGIN@~serviceusers/{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 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.

Set Owner

PUT /config/server/@PLUGIN@~serviceusers/{account-id}/owner_

Sets the owner group for a service user.

The owner group must be specified in the request body as a OwnerInput 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 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.

Delete Owner

DELETE /config/server/@PLUGIN@~serviceusers/{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

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 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
  }

Put Config

PUT /config/server/@PLUGIN@~config

Sets the configuration of the @PLUGIN@ plugin.

The new configuration must be specified as a ConfigInput 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>."
  }

JSON Entities

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 entity. The name field in the GroupInfo entities is not set since the names are already available as map keys.

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.

EmailInput

The EmailInput entity contains a new email address.

email: The new email address.

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.

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.

ServiceUserInfo

The ServiceUserInfo entity contains information about a service user. It has the same fields as a detailed AccountInfo and in addition the following fields:

created_by: The user that created this service user as a detailed AccountInfo 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 entity. Not set if no owner group is assigned.

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.

GERRIT

Part of Gerrit Code Review

@PLUGIN@ - /config/ REST API

Service User Endpoints

Create Service User

Request

Response

Get Service User

Request

Response

List Service Users

Request

Response

List SSH keys

Request

Response

Get SSH key

Request

Response

Add SSH key

Request

Response

Delete SSH key

Request

Response

Get Full Name

Request

Response

Set Full Name

Request

Response

Delete Full Name

Request

Response

Get Email

Request

Response

Set Email

Request

Response

Delete Email

Request

Response

Set/Generate HTTP password

Request

Response

Delete HTTP password

Request

Response

Get Active

Request

Response

Set Active

Request

Response

Delete Active

Request

Response

Get Owner

Request

Response

Set Owner

Request

Response

Delete Owner

Request

Response

Get Config

Request

Response

Put Config

Request

JSON Entities

ConfigInfo

ConfigInput

EmailInput

HttpPasswordInput

OwnerInput

ServiceUserInfo

ServiceUserInput

SEE ALSO

GERRIT