SSH

The API implements ssh.cgi as its communications interface and supports the following methods:

API Discovery

id=ssh

This CGI renders the process of retrieving and setting SSH parameters through the param.cgi obsolete. Devices that support both param.cgi and the SSH API will yield the same result regardless of method.

Use this example to configure your Axis device to enable SSH functionality.

1. Retrieve the SSH configuration for your Axis device using the url below with the POST method. The configuration will then be presented to you.

http://<servername>/axis-cgi/ssh.cgi

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSshInfo",
  "params": {}
}

2. Parse the JSON response.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSshInfo",
  "data": {
    "enabled": true
  }
}

{
  "apiVersion": "1.0",
  "context": "abc",
  "error": {
    "code": 1000,
    "message": "Internal error"
  }
}

This error will occur if the CGI encounters an internal error that makes it abort the operation.

3. Check the retrieved information and apply the new configurations.

http://<servername>/axis-cgi/ssh.cgi

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setSshConfiguration",
  "params": {
    "enabled": true
  }
}

4. The VMS will receive the a response and inform you of the result.

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setSshConfiguration",
  "data": {}
}

{
  "apiVersion": "1.0",
  "context": "abc",
  "error": {
    "code": 4003,
    "message": "Missing parameter(s)"
  }
}

This error will occur if the VMS has sent an incomplete request that was missing one or more of the required parameters.

API references

See getSshInfo for further instructions.

See setSshConfiguration for further instructions.

Use this example to check which API version you should use when you want to communicate with the Axis device.

1. Request a list containing the supported API versions.

http://<servername>/axis-cgi/ssh.cgi

{
  "context": "abc",
  "method": "getSupportedVersions"
}

2. Parse the JSON response.

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["1.0", "2.1"]
  }
}

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getSupportedVersions",
  "error": {
    "code": 8000,
    "message": "Internal error"
  }
}

This error will occur if the CGI encounters an internal error that causes it to abort the operation.

See getSupportedVersions for further instructions.

This API method is used to retrieve information about the SSH configuration from an Axis device.

Request

Security level

Administrator

Method

POST

Content-type

application/json

http://<servername>/axis-cgi/ssh.cgi

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getSshInfo"
}

Return value - Success

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getSshInfo",
  "data": {
    "enabled": <boolean>
  }
}

Return value - Error

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getSshInfo",
  "error": {
    "code": <error code>,
    "message": <string>
  }
}

Error code

There are no specific error codes for this method. General errors are listed in General error codes.

This API method will show you a list of supported API versions.

Request

Security level

Administrator

Method

POST

Content-type

application/json

http://<servername>/axis-cgi/ssh.cgi

{
  "context": <string>,
  "method": "getSupportedVersions",
  "params": {}
}

Return value - Success

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [<string>]
  }
}

Return value - Error

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getSupportedVersions",
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Error codes

There are no specific error codes for this method. General errors are listed in General error codes.

This API method is used to apply SSH functionality to an Axis device.

Request

Security level

Administrator

Method

POST

http://<servername>/axis-cgi/ssh.cgi

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "setSshConfiguration",
  "params": {
    "enabled": <boolean>
  }
}

Return value - Success

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "setSshConfiguration",
  "data": {}
}

Return value - Error

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "setSshConfiguration",
  "error": {
    "code": <error code>,
    "message": <string>
  }
}

Error codes

There are no specific error codes for this method. General errors are listed in General error codes.

These error codes are used by all API methods.

Please note that for internal CGI errors (1000) the HTTP response code is set to 500, whereas for any other CGI error the HTTP response code will be 200.

User authentication and authorization to use the CGIs are performed on the HTTP level and, if unsuccessful, will return the HTTP error code 401. The authorization of the internal services used by the CGIs are performed after both the HTTP authentication and authorization has passed, meaning it will always return the HTTP code 200 regardless of the outcome. Should it fail during the latter stage, the response will consist of an HTTP code 200 as well as JSON data containing the error 4002 (Authorization failed), which means that the CGI couldn't be authorized and thus unable to complete its task. This does not mean that you weren’t able to access the CGI itself.