Authentication for RESTful API

To use the RESTful API, you run GET, POST, PUT, or DELETE API calls. You can use various programs to run REST API calls; in these examples, we use curl. Regardless of which tool you use to run the calls, you must first authenticate.

Tip: When you use the Try it out action within a POST, PUT, or DELETE API call in a the REST interface within a browser, any previously authenticated tokens that you have are overwritten. For example, if you had the interface open in another tab, it is no longer authenticated. Additionally, the request might be denied by the security guard due to missing or invalid tokens. This happens when your current session is already logged into the interface. Clear your cache and try again.

Authenticating with a user name and password

The simplest way for HTTP basic authentication is to always provide a user name and password. For example, if you are using curl, specify the user name and password (the following example uses the built-in cluster administrator user account Admin with the default password Admin):

curl --header 'Accept: application/json' --user Admin:Admin --cacert /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem --tlsv1.2 
-X GET https://myresthost.example.com:8543/platform/rest/ego/v1/hosts

This example uses the default self-signed CA certificate for the --cacert option (the default certificate file is located at $EGO_TOP/wlp/usr/shared/resources/security/cacert.pem (for Linux®) and Installation_top\wlp\usr\shared\resources\security\cacert.pem Windows). For your production cluster, use a properly chained certificate that is signed by a trusted CA.

Alternatively, use the -k option (instead of the --cacert option) to specify an insecure connection.

Credential-based authentication with cookies

Credential-based authentication uses cookie-based session tokens and is recommended for secure authentication. This process is twofold: first generate the cookie file (which provides tokens that are valid for up to 8 hours), then reuse the generated cookie file in your GET, POST, PUT, or DELETE API call:

Generate the cookie file using the -c cookie_file option.
For example, if you are using curl, specify your user name and password (such as Admin for both), and the cookie file to be generated (for example, /tmp/cookie):
```
curl -X GET --cacert /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem --tlsv1.2 -c /tmp/cookie --header 'Accept: application/json' 'https://myresthost.example.com:8543/platform/rest/ego/v1/auth/logon' --user Admin:Admin
```
This example uses the default self-signed CA certificate for the --cacert option (the default certificate file is located at $EGO_TOP/wlp/usr/shared/resources/security/cacert.pem (for Linux) and Installation_top\wlp\usr\shared\resources\security\cacert.pem (for Windows). For your production cluster, use a properly chained certificate that is signed by a trusted CA.

Specify reuse of the generated cookie file using the -b cookie_file option in your API call. In this example, the API call is a GET call:

curl -X GET --cacert /opt/ibm/spectrumcomputing/wlp/usr/shared/resources/security/cacert.pem --tlsv1.2 -b /tmp/cookie --header 'Accept: application/json' 'https://myresthost.example.com:8543/platform/rest/ego/v1/hosts

Alternatively, use the -k option (instead of the --cacert option) to specify an insecure connection.

Following successful login, this command returns a token in an alphanumeric string format (such as 915ee7644f431e630dac68b9ab3e40bc). Add this token as a request parameter in all subsequent API calls.