Authentication Token

An access token is a unique identifier that's generated by windygrid service for the application requesting access to the API. The token is needed for security purposes to authenticate users to the application. A token can be an opaque string or a JSON web token.The token can be used to access the API resources without having to authenticate until it expires after four hours.

There are many api testing tools like cURL (standard commandline tool), Postman, and Fiddler to name a few. The documentation provides request examples in cURL, JavaScript and R.

An api call path is provided next to each method.

Method	Path	Description
POST	baseurl/users/token	Return a JSON Web Token (JWT) token after user id and password have been successfully validated. The JavaScript Web Token expire after 4 hours. The authentication token needs to be renewed prior to expiration by calling /users/renew. See below for more information.

Token Requested over Plain Text

The password is currently expected to be sent in plain text (not encrypted). This is partly done to avoid unnecessary complexity. We believe it is best to rely on transport security (HTTPS) to encrypt user credentials.

Token Request Examples

Token request in cURL with credentials embedded in code:

curl -k -i -X POST -d "{\"username\":\"123456\",\"password\": \"Abcde@1234\"}"\
 -H "Content-Type:application/json" https://webapps1.chicago.gov/windygridservice/rest/users/token

Sample token request that redirects the output to a file so the user can easily copy and paste the token value:

A text file is needed; inside the text file are credential placeholders in json format. Enter your city AD user id and password within the placeholders, remove the brackets and save the file in a location on your computer.

Sample Payload

    {
      "username": "123456",
      "password": "Abcde@1234"
    }

Next, access the command prompt from the start menu, navigate to the location of the saved text file. On the command line enter the request to obtain the access token.

curl -k -i -X POST -d @textfile-payload-name.txt https://webapps1.chicago.gov/windygridservice/rest/users/token > token.txt

Returned Sample Response

A token is returned in the response header as “X-AUTH-TOKEN:” The authentication token consist of three sections separated by a period(.): HEADER.PAYLOAD.SIGNATURE; the key X-AUTH-TOKEN is appended to the response header below:

HTTP/1.1 200 OK
Date: Tue, 23 Apr 2019 20:38:49 GMT
Server: JBoss-EAP/7
Expires: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
X-Powered-By: Undertow/1
Pragma: no-cache
Access-Control-Expose-Headers: X-AUTH-TOKEN
Access-Control-Allow-Origin: *
X-AUTH-TOKEN: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIzODE0MDQiLCJleHAiOjE1NTYwNjYzMjksImp0aSI6IjM4MTQwNCIsInJvbGVzIjoid2luZHlncmlkLHdpbmR5Z3JpZGFkbWluIiwicmVzb3VyY2VzIjoidHdlZXQsbW9iaWxlX2Fzc2V0cyxjb2xzLGJ1aWxkaW5nY29kZXNjb2ZmbGF3LGVudmlyb25tZW50YWxfZW5mb3JjZSxidWlsZGluZ192aW9sYXRpb25zLDMxMSxzMzExc3Isd2VhdGhlcixjZHBoX3N0b3JhZ2VfdGFua3MsY3JpbWVzLHMzMTF3byxlbnZpcm9ubWVudGFsX3Blcm1pdHMscHJvYmxlbWxhbmRsb3JkLHRyYW5zcG9ydGF0aW9uX3Blcm1pdHMsb3JkaW5hbmNlX3Zpb2xhdGlvbnMsZW52aXJvbm1lbnRhbF9pbnNwZWN0aW9ucyxtZXRzX2luY2lkZW50cyw5MTFwLGZpcmVfbW9iaWxlX2Fzc2V0cyxhc2Jlc3Rvc19kZW1vbGl0aW9uLGZvb2RpbnNwZWN0aW9ucyw5MTFmLGJ1aWxkaW5nX3Blcm1pdHMsJGFkbWluLGN0YSxudXJzaW5naG9tZXMsZW52aXJvbm1lbnRhbF9jb21wbGFpbnRzLHdlc3RfbmlsZV92aXJ1cyxidXNpbmVzc19saWNlbnNlcyxjcmFzaCIsImZuYW1lIjoiUmVnaW5hIiwibG5hbWUiOiJIaWdodG93ZXIifQ.32nHXt0UetqQM6eX47q3MZ2gHe2xE2sroPcoY67-X8VtjsmFkL-P-68qc2GOYaFeVk6IIEz5OkqWhu9-lXkN8w
Content-Length: 0
Set-Cookie: BIGipServerwebapps1.chicago.gov-443.app~webapps1.chicago.gov-443_pool=490100746.21308.0000; Secure; HttpOnly; path=/; Httponly; Secure

This token can be parsed using the jwt_decode JavaScript Web Token library.

Error Code

If user authentication fails, HTTP status code 401 (Unauthorized) is returned to the requester. For a complete list of response codes see HTTP Status Codes on Response.

JavaScript token request and querying data

var url = "https://webapps1.chicago.gov/windygridservice/rest";

//pass credentials as JSON payload, using city credentials authentication
    $.post( url + "/users/token", '{ "username": "your id", "password": "your password" }')
     .done(function( data, status, request ) {

//token is returned in header as 'x-auth-token'
    var token = request.getResponseHeader("x-auth-token");
       $( "#token" ).text( token );

//pass token to every subsequent requests using jquery setup
    $.ajaxSetup({
                 headers: {
                     "x-auth-token": token
                    }
                });

//get list of all datasets
    $.get(url + "/datasets", function (data) {

//just display the first one
    $( "#datasets" ).html("Found " + data.length + ", first dataset id=" + data[0].id);
            }, 'json');

//query 311 service requests
    $.get(url + "/datasets/s311sr/query", {q: {"$and":[{"when.creation_date":{"$gt":1555736400000}}]}}, function (data) {

//just display the first one
    $( "#results" ).html( "Found " + data.features.length + " records");
        }, 'json');
    });

Token Request in "R"

// Get username and password from file
    usr <- jsonlite::read_json("@textfile-payload-name.txt")$username
    pw <- jsonlite::read_json("@textfile-payload-name.txt")$password

//get token
    url <- "https://webapps1.chicago.gov/windygridservice/rest/"

        r <- httr::POST(url = paste(url,"users/token", sep=""), 
                body = sprintf('{"username":"%s", "password": "%s"}', usr, pw))
            token <- r$headers$`x-auth-token`

//get list of datasets
    r <- httr::GET(url=paste(url,"datasets", sep=""), 
               httr::add_headers("x-auth-token"=token))
//display datasets
    str(httr::content(r, "parsed"), 2)

// query example used in API call
// https://webapps1.chicago.gov/windygridservice/rest/datasets/s311sr/query?q={"$and":[{"when.creation_date":{"$gt":1556773200000}}]}&n=500

// display query from api call
    r <- httr::GET(
        url = paste(url,
                'datasets/s311sr/query?q={"$and":[{"when.creation_date":{"$gt":1556773200000}}]}&n=500', 
                sep=""), 
           config = httr::add_headers("x-auth-token"=token))
// display query
    str(httr::content(r, "parsed"), 2)

Renew Token

Method	Path	Description
POST	baseurl/users/renew	Renew the expiration date on an existing JSON Web Token (JWT) token. The existing token needs to be on the request header under key X-AUTH-TOKEN:.

Sample Response

No response is returned on token renewals but the authentication token will have a new expiration time thats appended to the response header, replacing the previous one. See 'X-AUTH-TOKEN' above for a sample token value.