Authentication API

Introduction

The CityGrid Authentication API allows applications to login and receive an access token for use in subsequent calls to other Advertising APIs.

Login Endpoint

The login endpoint allows applications to obtain an access token for API calls that require authentication. The token is obtained via HTTPS POST to:

api.citygrid.com/accounts/user/v2/login

Request Parameters

Parameter	Description	Required	Type

Parameter	Description	Required	Type
`username`	CityGrid username	Yes	String
`password`	CityGrid password	Yes	String

Request Headers

Header	Description	Required	Valid Values	Default

Header	Description	Required	Valid Values	Default
`Accept`	Requested format for the response	No	`application/json` `application/xml`	`application/json`
`Content-Type`	Media type of the request body	Yes	`application/x-www-form-urlencoded`
`developerToken`	The token received during registration	Yes	Valid token

Request Examples

Example 1: Request an access token to be returned in a JSON response


curl -X POST \
    -H 'Content-Type:application/x-www-form-urlencoded' \
    -H 'developerToken:myDevToken' \
    -d 'password=mypass&username=myuser' \
    'https://api.citygrid.com/accounts/user/v2/login'

Example 2: Request an access token to be returned in an XML response


curl -X POST \
    -H 'Accept:application/xml' \
    -H 'Content-Type:application/x-www-form-urlencoded' \
    -H 'developerToken:myDevToken' \
    -d 'password=mypassword&username=myname' \
    'https://api.citygrid.com/accounts/user/v2/login'

Response Properties

Property	Type	Description

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`authToken`	String	The token to pass in the header in subsequent API requests

Response Examples

Example 1: A JSON success response


{
  "response":{
    "field":"",
    "message":"Success",
    "code":"SUCCESS"
  },
  "authToken":"3dfbee9f079741d3a987df6854286182"
}

Example 2: A JSON error response


{
  "response":{
    "field":"",
    "message":"No account found for the username and password provided",
    "code":"ACCOUNT_NOT_FOUND"
  },
  "authToken":""
}

Example 3: An XML success response


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<authTokenResource>
  <authToken>12e35a0538774c1377c6cf5dac2ce292</authToken>
  <response>
    <code>SUCCESS</code>
    <field></field>
    <message>Success</message>
  </response>
</authTokenResource>

Example 4: An XML error response


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<authTokenResource>
  <authToken></authToken>
  <response>
    <code>ACCOUNT_NOT_FOUND</code>
    <field></field>
    <message>No account found for the username and password provided</message>
  </response>
</authTokenResource>