Authentication and Security with the Akana API Platform API

Authentication of platform API users is managed by means of the Akana API Platform authorization cookie.

The platform API includes a powerful set of operations for completing many activities relating to app and API management. Some of these operations, which only retrieve information publicly available on the platform, do not require any sort of authentication to run them. Many operations, for example those relating to an individual user, require at least a platform login. Operations relating to adding, changing, or deleting apps, APIs, and other resources require additional authentication to verify that the individual running the operation has the authority to make the changes. Authentication is verified by means of a session cookie which is sent to the individual user at login.

In working with the platform API, you'll need to make sure you have the appropriate access rights for running the various operations. This topic provides information on authentication requirements and how to obtain the necessary credentials to run operations. It also includes information about the session cookie, how to end the session, and the special CSRF prevention header.

It includes:

Determining authentication requirements

The documentation for each operation includes an Authorization Roles/Permissions section that tells you the roles that are authorized to run the operation. Some examples:

Operations you can run without login

Some operations, which retrieve general information not marked as Private (see Public and private resources below), do not require any authentication at all. Anyone can run these operations at any time using a standard HTTP browser or a general purpose REST API client such as RESTClient, Postman, or soapUI, or using an app (implemented with any technology) that is consuming the platform API.

The operations you can run without logging in are all "read" operations using the HTTP verb GET. Some examples:

  • GET /{contentpath}: Retrieves a specific content document. To retrieve content, no login is required, unless the content is marked as Private (see Public and private resources below).
  • GET /api/apis: Returns a list of APIs. Again, APIs marked as Private are not returned, but all APIs marked as Public are visible to all users in the Akana API Platform user interface, whether logged in or not, and anyone can perform this operation via the API without logging in.

Authenticating as a logged-in user

Before running API operations that require login, you'll need to perform a one-time signup via the user interface or API. To complete the signup process, sign up using the Community Manager developer portal or the Users service.

Once you've completed that process, you'll be able to use your user ID and password to log in via the API using the POST /api/login operation.

When you run the POST /api/login operation, you'll need to get the session and CSRF cookies from the response and include them in the request headers for subsequent operations. For more information, see The session cookie below. In many cases, technologies used in applications automatically remember the cookie received in the Login response and include it in subsequent requests.

You'll need to have additional roles to run certain operations; for per-operation authentication requirements, refer to the Authorization Roles/Permissions section in the documentation for each operation. For general information about roles, see Operations that require additional authorization roles / permissions below.

You'll also need to renew the session cookie after a certain period of time, or after certain events. See Renewing the session cookie below.

You don't need to be logged in to run operations that require no authentication (see Operations you can run without login above).

For information about SSO login scenarios, refer to Managing SSO Login on the Platform.

Operations that require login

Certain operations relating to an individual user, such as changing the password, can only be performed by the individual user, and require login.

Some other operations can be performed by an individual user or an Admin; for example, GET /api/users/{UserID}/board, which returns a list of Board items for a specific user.

Some more examples of user-related operations that require login:

Public and private resources

Key resources on the platform—APIs, apps, and groups—can have restricted visibility. They can be designated as Public, Private (Limited), or Registered Users. Public resources are broadly available and visible; Private resources are available, and visible, only to users who have been invited to have visibility of the resource and who have accepted the invitation. Resources with a visibility of Registered Users are visible to all users who have logged in.

The user interface uses the term Private to indicate limited visibility, but the API uses the term Limited.

The visibility setting of a resource affects the results of many API operations even when the operation itself doesn't require login. For example, a user who is not logged in can run the GET /api/apis operation, and receive a list of APIs in the response; but APIs marked as Private are not returned. A user who has access to the private APIs can run the same operation and get a broader set of results.

Operations that require additional authorization roles / permissions

All operations relating to adding, changing, or deleting apps, APIs, and other resources require additional authentication to verify that the individual running the operation has the authority to do so.

In general, operations relating to a specific app can be run by an app team member, a Business Admin, or a Site Admin; operations relating to an API can be run by an API Admin, Business Admin, or Site Admin.

For more information on the various roles and the permissions that generally go along with them, refer to Authorization Roles on the Platform.

When you run the POST /api/login operation, the response includes a session cookie which you'll need to make sure is included in the request headers for subsequent operations. If you're using a browser-based client, the cookie is probably sent automatically, but if not, you must explicitly include it.

There are a few operations that don't require a session cookie, such as password reset (POST passwordmanagement/sendPasswordResetCode), but most do. Required permissions are specified in the documentation for each operation; if an operation requires login, it requires the session cookie in the request. An example of the set-cookie header is shown below.

Set-Cookie: AtmoAuthToken_acmepaymentscorp=TokenID%3D9d37c51c-7f02-11e8-ba7b-b1224c287743%2Cclaimed_id%3Durn%3Aatmosphere%3Auser%3Aacmepaymentscorp%3Adec20fc3-866f-44c5-a440-f2f08421a2ae%2CissueTime%3D1530650983939%2CexpirationTime%3D1530652843913%2CUserName%3Dadminacmepaymentscorp%2CUserFDN%3Ddec20fc3-866f-44c5-a440-f2f08421a2aacmepaymentscorpmation%2CAttributesIncluded%3Dfalse%2Csig%3Dd-BlqJhni3I1zv-wEZ6cym_pjctqnfSIEdkrKZHMu2Nvd-dEIDfBFxOhbafyQ1li_ejmRPVYMwHqzyWXJ7agl4vEwqb-1_fc7kjwss6IsFxJ_iJV89cnUBp31u88CF-GAFA1zpLwJZX19RLq_nxtx2loBlJEYjG5Lmtq9q6OOtf058E6sZ4LnVOxXrbL0sXG2PtYGgaSBQVGsWjykU1Lj1BHxNM29C-MYLdVLSWhdcQm04fJhcMHys3nO0Np0zv3KIjvMM2buG7rHl3q_oYn83Umnmb_qP3bHSjwbvLJefreQkHkEQe8b0pVCRNwJ3eDq_Nk-UIEVIuqu5G8dMXWEA

For more information and examples, refer to Cookies in the Akana API Platform.

You'll also need to renew the cookie, after 30 minutes or after certain events. See Renewing the session cookie below.

CSRF prevention header

Many operations require the X-Csrf-Token_{fedmemberID} request header, which is constructed using the CSRF cookie. Depending on platform settings, the CSRF cookie is returned at login, and this custom header is required for a successful API call. For details on how to retrieve the CSRF cookie and use it to construct the X-Csrf-Token_{fedmemberID} header, see CSRF Prevention on the Platform.

An example of the Csrf-Token_{FedmemberID} cookie is shown below.

Csrf-Token_acmepaymentscorp=TokenID%3D13544611-3486-11e5-9f5c-cb8d33c7f3c7%2CexpirationTime%3D1438020415969%2CUserFDN%3D5a48b51d-b726-460f-bec5-8fb4e392137c%252Eacmepaymentscorp%2Csig%3DMKd7acZkLzsMIalD2LFhmuLPy58xa-NlxoWucWi3WVfO8UTsz_t88fCjQIQHKH-pRol_1wsGVHRnz3riAl7eKrRYEo68XOMn1UnoMYXQUX9mTGtGoTXgu61Dk7vIIiVhBJV1AIRZiHKoDim04hq-tjw8NIeHdH6DV7M2COAaTZA

The corresponding X-Csrf-Token_{fedmemberID} response header is shown below.

X-Csrf-Token_acmepaymentscorp=TokenID%3D13544611-3486-11e5-9f5c-cb8d33c7f3c7%2CexpirationTime%3D1438020415969%2CUserFDN%3D5a48b51d-b726-460f-bec5-8fb4e392137c%252Eacmepaymentscorp%2Csig%3DMKd7acZkLzsMIalD2LFhmuLPy58xa-NlxoWucWi3WVfO8UTsz_t88fCjQIQHKH-pRol_1wsGVHRnz3riAl7eKrRYEo68XOMn1UnoMYXQUX9mTGtGoTXgu61Dk7vIIiVhBJV1AIRZiHKoDim04hq-tjw8NIeHdH6DV7M2COAaTZA

The session cookie includes certain pieces of information that might change during the session as a result of the user's actions. For example, it includes information about the user's APIs, apps, and groups. If this information changes, the cookie must be renewed, and the new cookie must be used from that point onwards.

Once the user is logged in, if an operation is invoked that requires this cookie to be updated, the response to the operation includes the updated cookie in a Set-Cookie response header. The client can use the new cookie or, alternatively, the client can renew the cookie using the POST /api/login/renewToken operation.

For example, let's say that you want to use the API to accept an invitation to a group and then invite other members to that group. The operation for accepting a group invitation, POST /api/groups/requests/{MembershipRequestID}/actions, includes an updated cookie in a Set-Cookie response header, and also includes the following response header:

Atmo-Renew-Token: renew

This indicates that you must use the new cookie from the response in additional operations.

You can renew the cookie manually at any time by using the POST /api/login/renewToken operation.

Ending the session

When your session is complete, remember to log out using the GET /api/login/endsession operation.

If the session has not been ended, and the renew token is not invoked, the session expires when the token expires.