Troubleshooting the REST API

To start understanding errors from the REST API, examine the status code of the response along with the response body, if present. If that does not help, and you have access to the appliance's logs, then look at the log file for the REST API subsystem (setting the log level to DEBUG temporarily can be useful). In addition, here are some specific scenarios you may encounter:

I can't connect to the API at all over HTTPS

By default the REST API is only accessible over HTTPS. However, if you have not configured HTTPS then requests for any endpoint will fail to connect:

curl https://appliance/api/about

curl: (7) couldn't connect to host

Either configure HTTPS, or enable API access over HTTP, though this is only recommended for testing.

I keep getting 403 Forbidden errors back from the API

This could happen for a number of reasons.

If you are trying to access the REST API over HTTP then you will receive a 403 error if HTTP access is currently not allowed. This could either be because:

• Your appliance is in the default configuration, or
• You enabled API access over HTTP, but then also enabled HTTP to HTTPS redirection. This disables HTTP access to the API again.

Access to the API over HTTP is not recommended. 

However, if you do want to enable this for testing purposes, go to the HTTPS Configuration page in the user interface.

 If your HTTPS configuration is fine but you still receive 403 errors then the user accessing the API may not have permissions to perform the actions required by the endpoint. Some endpoints require more permissions than others - particularly those that access the vault or credentials, or those that create or modify resources (for example, submitting a new discovery run). To check if this is the case, try an endpoint like /discovery/runs, which requires less permissions than some of the others:

curl -i -X GET -H 'Authorization: bearer <your_token>' https://appliance/api/v1.0/vault/credentials

HTTP/1.1 403 Forbidden
{
    "code": 403,
    "message": "Permission denied",
    "transient": false
}


curl -i -X GET -H 'Authorization: bearer <your_token>' https://appliance/api/v1.0/discovery/runs

HTTP/1.1 200 OK
[]

If you can at least access some endpoints successfully, then your problem is likely to be a lack of permissions. If all endpoints are giving you back a 403 error then your user may not have "api-access" permission to access the REST API at all. In both cases, a BMC Discovery Administrator can review your permissions.

I keep getting 401 Unauthorized errors back from the API

This indicates that you could not be authenticated using the token expected in the HTTP "Authorization" header. This could be for a number of reasons:

• The "Authorization" header itself is missing or invalid.
• The token is missing from the header, or is invalid.
• The token has expired. Note that tokens only expire if they are generated from the /api/token endpoint (as opposed to being generated in the user interface). In this case, you can generate a new one with another call to the same endpoint. If you are using the Swagger UI, the interaction with /api/token is hidden from you, but you can trigger another call to the endpoint by refreshing the Swagger UI and entering your username and password again.
• The user that owns the token has been deactivated or deleted.

I can't generate a token for the System user

The System user cannot be used to access the API by design. This is to encourage more secure use of permissioning in the system, and also because if the System user's API token was revealed there is no way to delete this user.