Cookies in the Akana API Platform 

This topic provides information about the use of cookies in the platform, including:

Session Cookies

API calls from the Akana API Platform use the custom cookies shown below. The AtmoAuthToken cookie is quite long—over 400 characters.

Note: The only requirement from the developer using the Akana API Platform API is that the app supports cookies. The Akana API Platform takes care of the rest. If your development environment supports automatically capturing and sending the Akana API Platform cookie you don't need to do anything. If it doesn't, you'll have to make sure the cookie that the Akana API Platform returns upon login is sent with every request and that the token is renewed when information stored in the token changes, such as when a user adds an app.

Cookie Name Description/Values
AtmoAuthToken_{fedmemberid}

A tenant-specific cookie. This is the Akana API Platform authorization token. This cookie indicates the level of access allowed. It is valid only for 30 minutes and must be renewed at that time. It also includes other information, such as the APIs, apps, and groups the user is a member of. When any of this information changes, the token must be renewed.

Note: When your app invokes the POST /api/login method, the Akana API Platform sets the cookie; you don't need to do anything. Your app must support cookies, so that the cookies that are set by the API responses can be sent back as part of the subsequent requests.

Csrf-Token_{fedmemberid} An additional cookie used when the CSRF prevention feature is in effect. The value is then used in the X-Csrf-Token_{fedmemberID} custom header in request messages. For more information, see CSRF Prevention on the Platform.

Below is an example of an AtmoAuthToken cookie sent by the GET /api/legals/{LegalDocumentID} operation. Line breaks have been added for display reasons.

Cookie:  AtmoAuthToken_acmepaymentscorp=TokenID%3D94299147-d006-11e3-a97a-e4f95250745e%2Cclaimed_id%3Durn%3A
acmepaymentscorp%3Auser%3Ademo%3Auser29005%2CissueTime%3D1398821242584%2CexpirationTime%3D1398823042538%2C
AttributesIncluded%3Dfalse%2CUserFDN%3Duser29005%252Edemo%2CUserName%3Ddemo-MaryMead%2Csig%3DHXlox2IqdCf1b
I060ZoGQESQjhQJz5x_uilEZGifnL4gUr_cFaepQoebfmJJCmrUVqoF0yFkHnuhAMxnVzHUnnbIbfvwqOyZ2gClm4n8IyHza2m_PxfMA
OpM8UWQ0jfwReP7mbU1E2OyH69uRCgg5SsLw9RQLzyxojBGslxXDvo

Below is an example of a CSRF token cookie returned by the POST /api/login operation. Line breaks have been added for display reasons.

Csrf-Token_acmepaymentscorp=TokenID%3Deaa11ad3-0884-11e5-902f-82920a2a00d8%2CexpirationTime%3D1433182067000
%2CUserFDN%3D8431248b-4863-45c2-b7b4-09148a92a50d%252Eacmepaymentscorp%2Csig%3DDeCpOJ1SNKV6wbqmG_ErBd8ojdA
7PxuqYbf09qDGrt0bO_81perAAde56fTagQqfOK54ZuxUVfOQtiAPq9h8KOseU87tyfhlmkYPDEqwlwvsWMV6ylXofH-bo5RHPorW-B-lppEz
AVkr8n9CapHdlQ9f-E1k44Pqlg8t7iAgk2M

OAuth cookie

If OAuth is being used, when the user (resource owner) authenticates with the authentication server, the platform generates an OAuthToken_{OAuthProviderName} cookie. This cookie identifies the logged-in user and the specific roles associated with the user. The app then uses this cookie in subsequent requests to the platform's OAuth Provider, for session management and grant administration, until grant authorization is complete. For non-browser scenarios, the app must save this cookie and include it in every request.

For more information about OAuth operations, refer to the OAuth API documentation.

Below is an example of an OAuthToken_{OAuthProviderName} cookie returned by the POST /oauth/login/renewToken operation in the Set-Cookie header. Line breaks have been added for display reasons.

Set-Cookie: OAuthToken_acmepaymentscorp: TokenID%3D57d30fc7-240e-11e5-a1b9-8945fbb2b0eb%2Cclaimed_id%3DLDAP_acmepaymentscorp%5Ceng100
%2CissueTime%3D1436207972636%2CexpirationTime%3D1436208572626%2Csig%3DlOsIenU6JM-dYquJKhKMdKarQRtef4ALY5Abuls7KV5jaPgWapM1w0Y
thq0I1hJvMJ7xlWj8haU3OvM4b6I3LgGWGvw5_Uws935JKLW57xiti_UC2IvxFDrAIg4xx2k-x-icqUDsWfVGNfjWlun43_uRM667RjGOkh_ZmU2xq0Q

The example below is returned by the GET /oauth/auz/grants/{GrantID}/authcomplete operation.

Set-Cookie: AtmoAuthToken_acmepaymentscorp: TokenID%3D480a3a7c-240e-11e5-a1b9-8945fbb2b0eb%2Cclaimed_id%3Durn%3Aacmepaymentscorp%3Auser
%3Aacmepaymentscorp%3A8fb17266-354a-4032-96fb-2208ae7b4da4%2CissueTime%3D1436207946162%2CexpirationTime%3D1436209746144%2CAttributes
Included%3Dfalse%2CUserFDN%3D8fb17266-354a-4032-96fb-2208ae7b4da4%252Eacmepaymentscorp%2CUserName%3Dadminacmepaymentscorp%2Csig
%3Dd5YEgxmZQaCgfp64gs0EL1ttryepO3kWTwu4gO12OxLF6sjpcrojVKUf0X8heu9eoi8WlEd9ZIN7vPNgi6pu-XZ883L-OkD9fYnN4ktbRPwHQ2Phaa1H1bXaCpfgpeI8q6u
DjeqX_awH70N6-QQKrhF5n9Lm5PYCKciKNWTSWVooauthRedirectInfoCookie: %7B%22accessTokenUrl%22%3A%22%2Fapi%2Fdevconsole%2Foauth%2Faccesstoken%22
%2C%22providerEndpoint%22%3A%22%2Fapi%2Fdevconsole%2Foauth%2Faccesstoken%22%2C%22queryString%22%3A%22session_key%3Dapiv%253D090888
a5-27f8-454e-8319-c7900d1da4bc.acmepaymentscorp%2526scope%253DScope1%2526appRuntimeId%253D5tRKCWjfz599pLJ8Te4tvn1D.acmepaymentscorp
%2526granttype%253Dauthorization_code%2526policy_type%253DOAuth%2525202.0%2526appsecret%253De4d5949f72473acc151b34065f69169099ebe732
%2526appid%253Dacmepaymentscorp-5tRKCWjfz599pLJ8Te4tvn1D%2526token_url%253Dhttp%253A%252F%252F{hostname}%252Foauth%252Foauth20%252Ftoken%
2526opname%253DGetDiscussions%2526policy_key%253Doauth%2526guid%253Daf880c48-1389-4da4-98e5-2fb29dcca155%2526auz_url%253Dhttp%253A
%252F%252F{hostname}%252Foauth%252Fauz%252Fauthorize%2526callback%253Dhttp%253A%252F%252F{hostname}%252Fui%252Fapps%252Facmepaymentscorp
%252F_VcuNfhlXb0PE8hHDxAx9OhA%252Fresources%252Fconsole%252Fglobal%252Foauthclientredirect.html%253Fdynamic%25253Dtrue
%2526signature_method%253DSharedSecret%2526apienv%253DProduction%2526token_verb%253DPOST%22%7D
OAuthToken_acmepaymentscorp: TokenID%3D57d30fc7-240e-11e5-a1b9-8945fbb2b0eb%2Cclaimed_id%3DLDAP_acmepaymentscorp%5Ceng100
%2CissueTime%3D1436207972636%2CexpirationTime%3D1436208572626%2Csig%3DlOsIenU6JM-dYquJKhKMdKarQRtef4ALY5Abuls7KV5jaPgWapM1w0Y
thq0I1hJvMJ7xlWj8haU3OvM4b6I3LgGWGvw5_Uws935JKLW57xiti_UC2IvxFDrAIg4xx2k-x-icqUDsWfVGNfjWlun43_uRM667RjGOkh_ZmU2xq0Q

Short-term cookies

As well as the session cookies, the developer portal also uses cookies very briefly with certain features, in the following scenarios:

  1. Dev Console with OAuth Policy

    If you are using Dev Console with OAuth policy, there is a cookie used in the Dev Console feature that is set in the main page of the user interface so that it can be read in a popup window. It is deleted as soon as it has been read in the popup window. The platform does this to work around browser-enforced security, since the OAuth provider is usually from a different URL than the developer portal URL. This cookie is live in Dev Console only for a very short time, probably a few milliseconds.

  2. Third-Party Login with Google and Facebook (not LDAP)

    If you are using a third party such as Google or Facebook for login (not LDAP login), when the user logs into the portal for the first time, the portal uses a transient cookie to exchange information between the SSO login page and the signup page, in order to complete the signup page. This cookie stays live only for a very short time, probably a few milliseconds.

Optional Google Analytics cookies

The platform supports the option to enable Google Analytics for platform pages. This is controlled by a database setting; in the TENANTS table, it's the ANALYTICSACCOUNTID column. By default, Google Analytics cookies are not enabled (value set to null).

Google Analytics cookies are prefixed with __utm. For example:

  • __utma=120274954.1033981115.1360618092.1367978778.1368109070.82;
  • __utmz=120274954.1360695664.4.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none);
  • __utmc=120274954;
  • __utmb=120274954.9.10.1368109070;

Related Topics