Using the admin endpoints

Many of the admin endpoints in the REST API support the POST method, which you must call through a command-line tool such as postman or curl. All the admin endpoints require authentication, which means that you must log in to the server as an administrator and retrieve a cookie before you can call them.

Before you begin

To use the admin endpoints, you must log in as a user that has the necessary permission. For example, to provide a user with the i2:Administrator permission, you must use command access control to allocate it to a group that they're a member of. For more information, see Configuring command access control.

About this task

The following steps demonstrate how to use curl to POST to an admin endpoint.

You can find the REST API reference documentation at the following URL on the i2 Analyze server: http://<host_name>/<context_root>/doc. For example, http://localhost/opal/doc.

Procedure

If the curl utility is not available on your server, download it from the project website at https://curl.haxx.se/download.html.
Open a command prompt and use curl to log in to the i2 Analyze server and retrieve an authorization cookie:
```
curl -i --cookie-jar cookie.txt
     -d j_username=user_name
     -d j_password=password
     http://<host_name>/<context_root>/j_security_check
```
This command connects to the specified i2 Analyze server as the specified user, retrieves the authentication cookie, and saves it to a local file named cookie.txt. The LTPA token in the cookie is valid for 2 hours.
When the command completes, the response from the request is displayed. If the retrieval is successful, the first line of the response is:
```
HTTP/1.1 302 Found
```

After you retrieve and save the cookie, you can POST to an admin endpoint. When you do so, include the cookie file that you received when you logged in.

The following command is an example of a POST to the admin endpoint for reloading the live configuration:
```
curl -i --cookie cookie.txt
     -X POST 
     http://<host_name>/<context_root>/api/v1/admin/config/reload
```
When the command completes, the response from the request is displayed. If the retrieval is successful, the first line of the response is:
```
HTTP/1.1 200 OK
```
If you see the HTTP/1.1 403 Forbidden response code, then either the user for which you retrieved the token does not have the necessary command access control permission, or the token has expired:
- If your token has expired, you can get a new one by running the command in Step 2 again.
- If your user does not have the i2:Administrator permission, see Configuring command access control to provide the user with the permission.
Note: The reload method updates the configuration without requiring a server restart, but logged-in users might experience a short period of disruption when you run it.