Authentication via API

Related Tags: api integration user management

To manage authentication via API, the GoodData platform enforces a two-phased approach.

  1. Phase 1: Using the login API resource, a username and password are authenticated against the platform. If valid, the Super Secure Token (SST) is returned.

    This token is valid for 16 days before it needs to be renewed.
  2. Phase 2: The SST is inserted into the request as a Cookie to the token API resource. The Temporary Token (TT) is returned. This token is valid for a few minutes and must be renewed.

    NOTE: The TT is valid for 10 minutes exactly. If a Status Code 401 message is returned containing an empty value for GDCAuthTT, you can simply re-issue the Phase 2 call to request a new Temporary Token, as long as the SST token is still valid.

NOTE: Only with a valid Temporary Token can a user access resources through the GoodData platform. If no TT token is present, an HTTP Status Code 401 error is returned.

Examples using curl are provided of each call and response.

Phase 1 - Authenticate

In Phase 1, you query the login resource to authenticate and retrieve the SST.

Call TypePOST
API Resource/gdc/account/login

Request Body:

{
  "postUserLogin": {
    "login": "user@company.com",
    "password": "YourPassword",
    "remember": 1
  }
}

Response Header:

Set-Cookie: "GDCAuthTT=; path=/gdc; expires=Mon, 30-Jul-2012 09:12:42 GMT;
secure; HttpOnly, GDCAuthSST={super-secured-token}; path=/gdc/account; secure;
HttpOnly" Content-Type: "application/json"

NOTE: The value for {super-secured-token} must be retained for use in Phase 2.

Response Body:

{
  "userLogin": {
    "profile": "/gdc/account/profile/USER-ID",
    "state": "/gdc/account/login/USER-ID"
  }
}

Curl Example

In this example, curl is used to initiate the authentication.

Request:

curl --include --header "Accept: application/json" --header "Content-Type: 
application/json"      --request POST      --data-binary
"{\"postUserLogin\":{\"login\":\"joe.user@gooddata.com\",\"password\":\"MyPassword\",\"remember\":1}}" 
"https://secure.gooddata.com/gdc/account/login"

The above defines and issues a POST of a JSON request to the https://secure.gooddata.com/gdc/account/login API endpoint in the following structure:

{
    "postUserLogin": {
        "login" : "joe.user@gooddata.com",
        "password" : "MyPassword",
        "remember" : "1"
    }
}

Response Header:

The response header looks like the following.

HTTP/1.1 200 OK
X-GDC-REQUEST: iqrVtfEOwr0GoLzW
Server: Apache
Set-Cookie: GDCAuthTT=; path=/gdc; expires=Sun, 08-Sep-2013 21:57:22 GMT; secure; HttpOnly
Set-Cookie: GDCAuthSST=onBcrYCkpgEnma3l; path=/gdc/account; expires=Thu, 24-Oct-2013 21:57:22 GMT; secure; HttpOnly
Expires: Mon, 26 Jul 1997 05:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
Pragma: no-cache
P3P: CP='IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT'
X-GDC-REQUEST-TIME: 76
Content-Type: application/json;charset=UTF-8
Content-Length: 143
Accept-Ranges: bytes
Date: Tue, 08 Oct 2013 21:57:22 GMT
X-Varnish: 1668849663
Age: 0
Via: 1.1 varnish
Connection: keep-alive

In the above, there are two important values:

  • GDCAuthSST - its value is the Super-Secured Token (SST)
  • GDCAuthTT - has no value for the Temporary Token (TT), which means that the user has not completed Phase 2 of validation or that the token has expired.

Response Body:

The response body contains URI references to the user profile and current state of the user.

{"userLogin":{"profile":"/gdc/account/profile/254c399a3f5131b7026313d4f8761410","state":"/gdc/account/login/254c399a3f5131b7026313d4f8761410"}}

Protection

The login resource is protected against brute-force attacks with a rate-limit mechanism. After a certain number of invalid login requests, the server returns a status code of 429, ‘Too many requests’. The response contains the ‘Retry-After’ HTTP header. This header specifies the period (in seconds) after which you can attempt to log in again. The number of seconds between attempts increases with each successive failed login (a status code of 401).

Phase 2 - Request Temporary Token

Call TypeGET
API Resource/gdc/account/token

Request Header:

Cookie: "$Version=0; GDCAuthSST={super-secured-token}; $Path=/gdc/account"
Accept: "application/json" Content-Type: "application/json"

Response Header:

Set-Cookie: "set-cookie: GDCAuthTT={temporary-token}; path=/gdc; secure; HttpOnly" 
Content-Type: "application/json"

NOTE: The {temporary-token} must be renewed every few minutes to be able to continue to access resources.

Curl Example

Request:

The following call references the SST (GDCAuthSST=onBcrYCkpgEnma3l;) to request the Temporary Token:

curl --include --header "Cookie: $Version=0; GDCAuthSST=onBcrYCkpgEnma3l;
$Path=/gdc/account" --header "Accept: application/json" 
--header "Content-Type: application/json"
https://secure.gooddata.com/gdc/account/token        

Response Header:

In the header is returned the Temporary Token (the value for GDCAuthTT):

HTTP/1.1 200 OK
X-GDC-REQUEST: tMCdpZisB9bJCLnW
Server: Apache
Set-Cookie: GDCAuthTT=ZarXTnKiW7mpA-9zJeXHbxwGfM-d0bpXe4n3niZdYNCMO2KuZ-QTpPtsNY33hIPfEYLotC-xG68tzIGyg06fX-CMFXUcQAynv541Buxby6LuZzeXGCulfGtA5RaADMpZ0_F1QuCfxUxPL9FAB9iFELR-jXReYFCeAcW-0sWxtZV7ImwiOiIwIiwidSI6IjE3Mzk4NyIsImsiOiJmNDEwOTA3Yi1kZTk4LTQ2OGItYmU5NS05MWJiMDM2MTdhZDYiLCJ1aWQiOiIyNTRjMzk5YTNmNTEzMWI3MDI2MzEzZDRmODc2MTQxMCIsInYiOjEzODEyNzAzOTZ9; path=/gdc; secure; HttpOnly
Expires: Mon, 26 Jul 1997 05:00:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
Pragma: no-cache
P3P: CP='IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT'
X-GDC-TIMESTAMP: 600
X-GDC-REQUEST-TIME: 22
Content-Type: application/json;charset=UTF-8
Content-Length: 2
Accept-Ranges: bytes
Date: Tue, 08 Oct 2013 22:03:16 GMT
X-Varnish: 1668872766
Age: 0
Via: 1.1 varnish
Connection: keep-alive

Using the Temporary Token

After the Temporary Token has been received, all subsequent requests using any GoodData API endpoint must reference the token.

Curl Example

In the following example, the Temporary Token is used to create a new user in the domain.

curl --include --header "Accept: application/json" --header "Content-Type: application/json" 
--request POST    --header "Cookie: GDCAuthTT=ZarXTnKiW7mpA-9zJeXHbxwGfM-d0bpXe4n3niZdYNCMO2KuZ-CulfGtA5RaADMpZ0_F1QuCfxUxPL9FAB9iFELR-jXReYFCeAcW-0sWxtZV7ImwiOiIwIiwidSI6IjE3Mzk4NyIsImsiOiJmNDEwOTA3Yi1kZTk4LTQ2OGItYmU5NS05MWJiMDM2MTdhZDYiLCJ1aWQiOiIyNTRjMzk5YTNmNTEzMWI3MDI2MzEzZDRmODc2MTQxMCIsInYiOjEzODEyNzAzOTZ9; path=/gdc; secure; HttpOnly"  --data-binary "{
 \"accountSetting\":{
    \"login\": \"anotheruser@domain.com\",
    \"password\":\"PASSWORD\",
    \"email\":\"anotheruser@gooddata.com\",
    \"verifyPassword\":\"PASSWORD\",
    \"firstName\":\"Another\",
    \"lastName\":\"User\",
}
}"      "https://secure.gooddata.com/gdc/account/domains/gooddata-auth-test/users"
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
X-GDC-REQUEST: sUTRvYeM0yQxzvGt
Location: /gdc/account/profile/be68282a3ea2bfd8e1beaadce1ec6c54
X-GDC-REQUEST-TIME: 133
Content-Type: application/json;charset=UTF-8
Content-Length: 63
Accept-Ranges: bytes
Date: Tue, 08 Oct 2013 22:06:20 GMT
X-Varnish: 1668883660
Age: 0
Via: 1.1 varnish
Connection: keep-alive

{"uri":"/gdc/account/profile/be68282a3ea2bfd8e1beaadce1ec6c54"

In the above call, the key information to include to reference the Temporary Token is the following:

--header "Accept: application/json" --header "Content-Type: application/json" --request POST
--header "Cookie: GDCAuthTT=ZarXTnKiW7mpA-9zJeXHbxwGfM-d0bpXe4n3niZdYNCMO2KuZ-CulfGtA5RaADMpZ0_F1QuCfxUxPL9FAB9iFELR-jXReYFCeAcW-0sWxtZV7ImwiOiIwIiwidSI6IjE3Mzk4NyIsImsiOiJmNDEwOTA3Yi1kZTk4LTQ2OGItYmU5NS05MWJiMDM2MTdhZDYiLCJ1aWQiOiIyNTRjMzk5YTNmNTEzMWI3MDI2MzEzZDRmODc2MTQxMCIsInYiOjEzODEyNzAzOTZ9; path=/gdc; secure; HttpOnly"

The data-binary value is the body of the request.