Roles


GET roles

Description

Get all permissible roles for the requester.

Resource URL

https://api.optionscity.com/roles
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Role
Response Type Standard

Parameters

NameDescriptionRequired?Type
embed_users Embed array of user ids belonging to role. No NumberArray
page 1-indexed page to retrieve. Default is 1. No Number
per_page Number of entries returned per page. Default is 20. No Number

Example Request

GET https://api.optionscity.com/roles

Example Response

{
  "id" : 1,
  "name" : "Back office role",
  "org_id" : 3,
  "org_name" : "ABC Organization",
  "users" : [ 1, 15, 112 ],
  "permissions" : [ {
    "resource" : "OrganizationResource",
    "access" : "NoAccess",
    "description" : "All organization settings (e.g. name, customer redirect URL)."
  }, {
    "resource" : "AccountResource",
    "access" : "ReadAccess",
    "description" : "Basic account information for all accounts in scope (belonging to an organization or shared with another organization via a trading group). This includes the account name, GMI #'s, etc.  Notably, it does not include risk limits."
  } ]
}

POST roles

Description

Create a new role.

Resource URL

https://api.optionscity.com/roles
Authentication Required
HTTP Methods POST
Media Types application/json
Response Object Role
Response Type Standard
Request Object Role

Example Request

POST https://api.optionscity.com/accounts
{
  "name" : "Back office role",
  "org_id" : 3,
  "users" : [ 1, 15, 112 ],
  "permissions" : [ {
    "resource" : "OrganizationResource",
    "access" : "NoAccess",
    "description" : "All organization settings (e.g. name, customer redirect URL)."
  }, {
    "resource" : "AccountResource",
    "access" : "ReadAccess",
    "description" : "Basic account information for all accounts in scope (belonging to an organization or shared with another organization via a trading group). This includes the account name, GMI #'s, etc.  Notably, it does not include risk limits."
  } ]
}

Example Response

{
  "id" : 1,
  "name" : "Back office role"
}

GET roles/:id

Description

Get a specified role.

Resource URL

https://api.optionscity.com/roles/:id
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object Role
Response Type Standard

Parameters

NameDescriptionRequired?Type
embed_users Embed array of user ids belonging to role. No NumberArray

Example Request

GET https://api.optionscity.com/roles/12345

Example Response

{
  "id" : 1,
  "name" : "Back office role",
  "org_id" : 3,
  "org_name" : "ABC Organization",
  "users" : [ 1, 15, 112 ],
  "permissions" : [ {
    "resource" : "OrganizationResource",
    "access" : "NoAccess",
    "description" : "All organization settings (e.g. name, customer redirect URL)."
  }, {
    "resource" : "AccountResource",
    "access" : "ReadAccess",
    "description" : "Basic account information for all accounts in scope (belonging to an organization or shared with another organization via a trading group). This includes the account name, GMI #'s, etc.  Notably, it does not include risk limits."
  } ]
}

PUT roles/:id

Description

Modify an existing role.

Resource URL

https://api.optionscity.com/roles/:id
Authentication Required
HTTP Methods PUT
Media Types application/json
Response Object Role
Response Type Standard
Request Object Role

Parameters

NameDescriptionRequired?Type
id The role ID for the role to modify. Yes Number

Example Request

PUT https://api.optionscity.com/roles/1
{
  "name" : "Back office role",
  "users" : [ 1, 15, 112 ],
  "permissions" : [ {
    "resource" : "OrganizationResource",
    "access" : "NoAccess",
    "description" : "All organization settings (e.g. name, customer redirect URL)."
  }, {
    "resource" : "AccountResource",
    "access" : "ReadAccess",
    "description" : "Basic account information for all accounts in scope (belonging to an organization or shared with another organization via a trading group). This includes the account name, GMI #'s, etc.  Notably, it does not include risk limits."
  } ]
}

DELETE roles/:id

Description

Delete a role.

Resource URL

https://api.optionscity.com/roles/:id
Authentication Required
HTTP Methods DELETE
Media Types --
Response Object None
Response Type Standard

Parameters

NameDescriptionRequired?Type
id The role ID for the role to delete. Yes Number

Example Request

DELETE https://api.optionscity.com/roles/1

GET roles/:id/users

Description

Get a specified role's members.

Resource URL

https://api.optionscity.com/roles/:id/users
Authentication Required
HTTP Methods GET
Media Types application/json
Response Object User
Response Type Standard

Example Request

GET https://api.optionscity.com/roles/12345/users

Example Response

[ {
  "email" : "first.last@example.com",
  "first_name" : "Doug",
  "last_name" : "Kurth",
  "user_type" : "Customer",
  "trading_capacity" : 1,
  "liquidity_provision" : 1,
  "commodity_deriv_indicator" : 0,
  "investment_decision" : 2345,
  "execution_decision" : 6789,
  "trader_id" : "5678",
  "is_professional" : false,
  "id" : 12345,
  "is_active" : false
} ]

Role Object

Description

A permission role.

Fields

Field Type Optional Description
id Number No The City API ID for the role.
name String No The name given to the role (e.g. Back office role).
permissions ObjectArray Yes An array of permission objects.
permission sub type Object Yes A permission object with resource and access (Read = 0, Write = 1, ReadWrite = 2) keys.

JSON Sample

{
  "id" : 1,
  "name" : "Back office role",
  "org_id" : 3,
  "org_name" : "ABC Organization",
  "users" : [ 1, 15, 112 ],
  "permissions" : [ {
    "resource" : "OrganizationResource",
    "access" : "NoAccess",
    "description" : "All organization settings (e.g. name, customer redirect URL)."
  }, {
    "resource" : "AccountResource",
    "access" : "ReadAccess",
    "description" : "Basic account information for all accounts in scope (belonging to an organization or shared with another organization via a trading group). This includes the account name, GMI #'s, etc.  Notably, it does not include risk limits."
  } ]
}

* Date and time elements are ISO-8601 string representations