Example: Using the CSRF header

This exercise uses the example of adding a group to demonstrate how to put together the CSRF header that you'll need for using the Community Manager developer portal API (POST, PUT, and DELETE operations).

It includes:

Note: The requirement for the CSRF header is determined by the Community Manager developer portal security settings. It could be configured to be required for all operations, or not required at all. By default, the CSRF header is not required for GET operations, but is required for all other operations.

Overview

In this exercise you'll:

  1. Log in. Operation: POST /api/login.
  2. Collect the name and value of the CSRF cookie that's returned with the login response, and use them to construct the CSRF header.
  3. Use the CSRF header to add a group. Operation: POST /api/groups.

Instructions

Follow the detailed instructions below.

To use the CSRF header to add a group in the Akana API Platform using the API

  1. Log in via the API, POST /api/login operation, using your own email and password in the body of the operation instead of the placeholder values given below.
    • HTTP method: POST
    • URL: https://{hostname}/api/login
    • Accept header: application/json
    • Content-Type header: application/json
    • Request Body: 
      {
  "email":"MyEmailAddress",
  "password":"MyPassword"
}

    The platform API returns the login cookie, which you'll need to send with the request headers for any operation that requires login, and the CSRF cookie (X-Csrf-Token_{fedmemberID}), which you'll need to use to put together the CSRF header.

  2. Add the group, using the POST /api/groups operation. In your API call, use the values below, modifying the URL path as needed, and filling your own values for all fields in the Request Body (URL encoding not needed). Tags are optional, but all other values are required.
    • HTTP method: POST
    • URL: https://{hostname}/api/groups
    • Accept header: application/json
    • Content-Type header: application/json
    • Request Body (this example includes the optional website address, but you can delete that value, keeping the line with an empty value): 
      {
  "Group":{
    "Name":"CSRF_Test_Group",
    "Description":"Group for testing CSRF token",
    "GroupType":"com.soa.group.type.independent",
    "Visibility":"Public",
    "Tag":[
      "CSRF"
    ]
  }
}
  3. Put together the CSRF header, as follows:
    1. Capture the name and the value of the Csrf-Token_{FedMemberID} cookie returned with the login response. For example, the name might be Csrf-Token_acmepaymentscorp. The value is a long string.
    2. For the header name, prepend X-. For example, if the cookie name is Csrf-Token_acmepaymentscorp, the header name is X-Csrf-Token_acmepaymentscorp.
    3. For the header value, use the cookie value.
  4. Send the API call. You will get a 200 response.
  5. When done, remember to log out using the GET /api/login/endsession operation. Use the following values:
    • URL: https://{hostname}/api/login/endsession
    • Accept header: application/json

Training video

The training video below walks you through the steps in this example and shows the results.