Authentication


Overview

City API uses OAuth 2.0 for authentication. Specifically, we support the implicit, password, authorization code, refresh grant types.

Regardless of the grant type, access to all secured resources should include the OAuth token in the Authorization header. Here's an example:

GET /products HTTP/1.1
Host: api.optionscity.com
Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw
Content-Type: application/json

With some endpoints you may first use HTTP basic authentication with your OAuth client ID and secret. In these cases you must base-64 encode the string literal {OAuth client ID}:{OAuth client secret} and submit an HTTP authorization header like this:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

API Keys

Accessing City API requires an API key. API keys are managed on your profile page.


GET oauth/authorize (implicit grant OAuth flow)

Description

Initiate an implicit grant OAuth flow to obtain an access token, authorization code or OpenID ID token. This authentication method is tailored for JavaScript clients that run in a browser. The client should redirect the user to this resource for authentication. Once authenticated, the user will be redirected back to your application with a token.

Resource URL

https://api.optionscity.com/oauth/authorize
Authentication Optional
HTTP Methods GET
Media Types
Response Object
Response Type Standard

Parameters

NameDescriptionRequired?Type
client_id The client_id of the application requesting the token. Obtained from the City API admin panel. Yes String
response_type 'token', 'id_token', 'token id_token' or 'code'. Yes String
redirect_uri The URL to which the user-agent should be redirected. Yes String
scope Scope must contain 'openid', but can include other scopes. Yes String
state Supports tracking arbitrary client state. Value will be passed back following authentication. No String

Example Request

GET https://api.optionscity.com/oauth/authorize?client_id=1234&response_type=token&redirect_uri=https://trader.optionscity.com&scope=openid

Example Response

HTTP/1.1 302 Found
Location: https://trader.optionscity.com#access_token=12345

POST oauth/token (password)

Description

Request a new OAuth access token. The payload must be submitted as form data and URL-encoded (content type application/x-www-form-urlencoded). The client ID and secret can either be submitted with HTTP basic authentication or included as parameters in the request body.

Resource URL

https://api.optionscity.com/oauth/token
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object Token
Response Type Standard

Parameters

NameDescriptionRequired?Type
client_id The client ID of the application requesting the token. Obtained from the City API admin panel. May alternatively be supplied via HTTP basic authentication. Yes String
client_secret The client secret of the application requesting the token. Obtained from the City API admin panel. May alternatively be supplied via HTTP basic authentication. Yes String
grant_type Should always be 'password'. Yes String
username The customer's username (e.g. dgcupps). Yes String
password The customer's password. Yes String
customer_id The ID of the customer for which you want to create a token (allows acting on behalf of customers for admins). No Number

Example Request

POST https://api.optionscity.com/oauth/token

Example Response

{
  "access_token" : "2YotnFZFEjr1zCsicMWpAA",
  "token_type" : "bearer",
  "expires_in" : 1209600,
  "refresh_token" : "tGzv3JOkF0XG5Qx2TlKWIA"
}

POST oauth/token (refresh)

Description

Refresh an OAuth access token. The payload must be submitted as form data and URL-encoded (content type application/x-www-form-urlencoded). The client ID and secret can either be submitted with HTTP basic authentication or included as parameters in the request body.

Resource URL

https://api.optionscity.com/oauth/token
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object Token
Response Type Standard

Parameters

NameDescriptionRequired?Type
client_id The client ID of the application requesting the token. Obtained from the City API admin panel. May alternatively be supplied via HTTP basic authentication. Yes String
client_secret The client secret of the application requesting the token. Obtained from the City API admin panel. May alternatively be supplied via HTTP basic authentication. Yes String
grant_type Should always be 'refresh_token'. Yes String
refresh_token The previously provided refresh token (e.g. tGzv3JOkF0G5Q2TlKWIA). If you used the implicit grant flow to authenticate, you should not provide this parameter (a refresh token was not provided). In these instances, the browser will provide the refresh token in a cookie. Yes String

Example Request

POST https://api.optionscity.com/oauth/token

Example Response

{
  "access_token" : "2YotnFZFEjr1zCsicMWpAA",
  "token_type" : "bearer",
  "expires_in" : 1209600,
  "refresh_token" : "tGzv3JOkF0XG5Qx2TlKWIA"
}

POST oauth/token (authorization code)

Description

Request a new OAuth access token with an authorization code. The payload must be submitted as form data and URL-encoded (content type application/x-www-form-urlencoded). The client ID and secret can either be submitted with HTTP basic authentication or included as parameters in the request body.

Resource URL

https://api.optionscity.com/oauth/token
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object Token
Response Type Standard

Parameters

NameDescriptionRequired?Type
client_id The client ID of the application requesting the token. Obtained from the City API admin panel. May alternatively be supplied via HTTP basic authentication. Yes String
client_secret The client secret of the application requesting the token. Obtained from the City API admin panel. May alternatively be supplied via HTTP basic authentication. Yes String
grant_type Should always be 'authorization_code'. Yes String
code The authorization code. Yes String

Example Request

POST https://api.optionscity.com/oauth/token

Example Response

{
  "access_token" : "2YotnFZFEjr1zCsicMWpAA",
  "token_type" : "bearer",
  "expires_in" : 1209600,
  "refresh_token" : "tGzv3JOkF0XG5Qx2TlKWIA"
}

GET oauth/logout

Description

Logs the user out of City API.

Resource URL

https://api.optionscity.com/oauth/logout
Authentication Optional
HTTP Methods GET
Media Types
Response Object
Response Type Standard

Parameters

NameDescriptionRequired?Type
client_id The client_id of the application requesting the token. Obtained from the City API admin panel. Yes String
redirect_uri The URL to which the user-agent should be redirected. Redirected to the referrer if not provided. No String

Example Request

GET https://api.optionscity.com/oauth/logout?client_id=1234&redirect_uri=https://trader.optionscity.com

Example Response

HTTP/1.1 302 Found
Location: https://trader.optionscity.com

GET oauth/client

Description

Retrieves the oAuth Client keys for the authenticated user.

Resource URL

https://api.optionscity.com/oauth/client
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object API Key
Response Type Standard

Example Request

GET https://api.optionscity.com/oauth/client

Example Response

[ {
  "client_id" : "59b85ac53d00006802b3be4c",
  "name" : "metro_trader",
  "secret" : "0c4fd229-169b-48de-b92b-9b9a38b1d79c"
}, {
  "client_id" : "58dbd42d730100730118e5b4",
  "name" : "thompson_reuter",
  "secret" : "4732885a-dcb8-4029-a63e-e662d918a132"
} ]

POST oauth/client

Description

Requests an oAuth key on behalf of the user for the specified client name.

Resource URL

https://api.optionscity.com/oauth/client
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object API Key
Response Type Standard
Request Object API Key

Parameters

NameDescriptionRequired?Type
name The name of the application requesting access Yes String

Example Request

POST https://api.optionscity.com/oauth/client
{
  "name" : "metro_trader"
}

Example Response

{
  "client_id" : "59b85ac53d00006802b3be4c",
  "name" : "metro_trader",
  "secret" : "0c4fd229-169b-48de-b92b-9b9a38b1d79c"
}

PUT oauth/client

Description

Updates the application name for this API key.

Resource URL

https://api.optionscity.com/oauth/client
Authentication Required
HTTP Methods PUT
Media Types application/json
Response Object API Key
Response Type Standard
Request Object API Key

Parameters

NameDescriptionRequired?Type
client_id The client id of the application requesting access Yes String
name The updated name of the application requesting access Yes String

Example Request

PUT https://api.optionscity.com/oauth/client
{
  "client_id" : "59b85ac53d00006802b3be4c",
  "name" : "vela_metro"
}

Example Response

{
  "client_id" : "59b85ac53d00006802b3be4c",
  "name" : "vela_metro",
  "secret" : "0c4fd229-169b-48de-b92b-9b9a38b1d79c"
}

DELETE oauth/client/:client_id

Description

Removes an API key previous added for an application

Resource URL

https://api.optionscity.com/oauth/client/:client_id
Authentication Required
HTTP Methods DELETE
Media Types application/json
Response Object API Key
Response Type Standard

Parameters

NameDescriptionRequired?Type
client_id The client id of the application whose access is being revoked Yes String

Example Request

DELETE https://api.optionscity.com/oauth/client/59b85ac53d00006802b3be4c

Example Response

{
  "client_id" : "59b85ac53d00006802b3be4c",
  "name" : "metro_trader",
  "secret" : "0c4fd229-169b-48de-b92b-9b9a38b1d79c"
}

Token Object

Description

The response to a request for an OAuth token from a username and password.

Fields

Field Type Optional Description
access_token String No The token used to authenticate all subsequent requests (until the token expires).
token_type String No Always set to 'bearer'. Subsequent requests must indicate the 'bearer' token type in the authorization header.
expires_in Number No The number of seconds until this token expires.
refresh_token String No Token used to refresh the access token before it expires (e.g. tGzv3JOkF0XG5Qx2TlKWIA).

JSON Sample

{
  "access_token" : "2YotnFZFEjr1zCsicMWpAA",
  "token_type" : "bearer",
  "expires_in" : 1209600,
  "refresh_token" : "tGzv3JOkF0XG5Qx2TlKWIA"
}

API Key Object

Description

The API Key for a client that has been granted authorization on behalf of a user.

Fields

Field Type Optional Description
client_id String No The client ID of the application requesting access
name String No The name of the application that this API key/secret belongs to
secret String No The client secret that corresponds to the client id for this application

JSON Sample

{
  "client_id" : "59b85ac53d00006802b3be4c",
  "name" : "metro_trader",
  "secret" : "0c4fd229-169b-48de-b92b-9b9a38b1d79c"
}

* Date and time elements are ISO-8601 string representations