protocol.html

{% extends 'base.html' %}

{% block title %}SimpleFIN Protocol{% endblock %}

{% block content %}


{% macro anchor(name) -%}
<a class="clickanchor" name="{{ name }}" href="#{{ name }}">&sect;</a>
{%- endmacro %}


<div class="title"><img src="/img/logo.svg" class="logo"> SimpleFIN Protocol</div>

{% from 'navbar.html' import navbar %}
{{ navbar('protocol') }}

<div class="container-fluid">


  <div class="row-fluid section">
    <div class="content span8 offset2">
      
      <p>Last updated: {% include 'changedate.html' %}</p>
      <p>Version: 1.0-draft</p>

      <p>
        The SimpleFIN standard defines:
      </p>

      <ol class="std">
        <li><a href="#http-protocol">SimpleFIN HTTP protocol</a></li>
        <li><a href="#data-format">SimpleFIN data format</a></li>
        <li><a href="#recommendations">Recommendations for token management</a></li>
      </ol>

      <h2>{{ anchor('http-protocol') }}HTTP Protocol</h2>

      <h4>{{ anchor('players') }}Players</h4>

      <dl>
        <dt>{{ anchor('the-company') }}The Company</dt>
        <dd>
          This is a bank or other institution that people have accounts with.
        </dd>
        
        <dt>{{ anchor('server') }}Server</dt>
        <dd>
          An HTTP server operated by <span class="term">The Company</span>.  The <span class="term">Server</span> must require SSL for all communication with both the <span class="term">Browser</span> and the <span class="term">Reader</span>.  Connection attempts not
          over SSL must be dropped -- they must not be redirected to SSL.
        </dd>
        
        <dt>{{ anchor('account-holder') }}Account holder</dt>
        <dd>
          This is a person (or business) that has an account with <span class="term">The Company</span>.
        </dd>
        
        <dt>{{ anchor('browser') }}Browser</dt>
        <dd>
          A web browser being used by an <span class="term">Account holder</span>.
        </dd>
        
        <dt>{{ anchor('reader') }}Reader</dt>
        <dd>
          A <span class="term">Reader</span> is a piece of software that connects to a <span class="term">Server</span> to retrieve financial information pertaining to an <span class="term">Account holder</span>.  The <span class="term">Reader</span> may be a web app or a locally-run application.  The <span class="term">Reader</span> <strong>only</strong> has read access to the <span class="term">Server</span>.  The <span class="term">Reader</span> <strong>can not</strong> alter the financial data on the <span class="term">Server</span> in any way.
        </dd>

      </dl>

      <div class="print-chunk">
        <h4>{{ anchor('pieces') }}Pieces</h4>

        <dl>
          <dt>Access token</dt>
          <dd>
            An <span class="term">Access token</span> is the string used by the <span class="term">Reader</span> to authenticate with the <span class="term">Server</span>.  See <a href="#access-token" class="term">Access token</a> for details.
          </dd>

          <dt>Setup token</dt>
          <dd>
            A <span class="term">Setup token</span> is the token given to the <span class="term">Reader</span> by the <span class="term">Account holder</span>.  It includes an <span class="term">Access token</span>.  See <a href="#setup-token" class="term">Setup token</a> for more details.
          </dd>
        </dl>
      </div>

      <div class="print-chunk">
        <h4>{{ anchor('protocol-overview') }}Overview</h4>

        <p>
          Here is an overview of how the SimpleFIN protocol works:
        </p>

        <ol class="std">
          <li>
            The <span class="term">Account holder</span> uses a <span class="term">Browser</span> to visit the <span class="term">Server</span>, authenticate, and generate a new <span class="term">Setup token</span>.
          </li>
          
          <li>
            The <span class="term">Account holder</span> gives the <span class="term">Setup token</span> to the <span class="term">Reader</span>.  The <span class="term">Reader</span> extracts the <span class="term">Access token</span> from the <span class="term">Setup token</span>.
          </li>

          <li>
            The <span class="term">Reader</span> connects to the <span class="term">Server</span> (authenticating with the <span class="term">Access token</span>) and requests some portion of the <span class="term">Account holder's</span> financial information.
          </li>

          <li>
            The <span class="term">Reader</span> reuses the <span class="term">Access token</span> until it expires or is otherwise rendered invalid.
          </li>
        </ol>
      </div>

      <div class="print-chunk">
        <h4>{{ anchor('access-token') }}Access token</h4>

        <ul class="std">
          <li>
            Access tokens must be at least 40 characters in length.  <span class="term">The Company</span> may choose the length of token for their <span class="term">Server</span>.
          </li>

          <li>
            Access tokens must be made up of only the following set of characters:
            <div class="code-block">abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-</div>
          </li>

          <li>
            Access tokens must be mostly random.  Ideally, the token will be completely random.
          </li>

          <li>
            Access tokens must not be based on, or have the potential to reveal <span class="term">Account holder</span> credentials for <span class="term">The Company</span>.  A stolen <span class="term">Access token</span> should not reveal anything to the attacker which would allow the attacker to access the <span class="term">Account holder's</span> account (other than through the SimpleFIN protocol).
          </li>
        </ul>
      </div>


      <div class="print-chunk">
        <h4>{{ anchor('setup-token') }}Setup token</h4>

        <p>
          Setup tokens are Base64 encoded strings containing the URL for a <span class="term">Server's</span> SimpleFIN root URL and an <a href="#access-token">Access token</a>.  Here is a generic code description of the format:
        </p>

        <div class="code-block">base64encode(sfin_url + '\n' + access_token)</div>

        {% set sfin_root = 'https://sfin.example.com/foo/bar' %}
        {% set access_token = '18KadNuTXEnCS97rt3PGT9UjTVvL2PvochYN-Dhc' %}
        <p>
          For example, if my <span class="term">Server's</span> SimpleFIN root URL is:
        </p>
        <div class="code-block">{{ sfin_root }}</div>
        <p>
          and I have generated this <span class="term">Access token</span>:
        </p>
        <div class="code-block">{{ access_token }}</div>

        <p>
          then the decoded <span class="term">Setup token</span> is:
        </p>
        <div class="code-block">{{ sfin_root + '\n' + access_token }}</div>

        <p>
          and the Base64 encoded <span class="term">Setup token</span> is:
        </p>
        <div class="code-block">{{ (sfin_root + '\n' + access_token)|b64enc }}</div>
      </div>


      <h4>{{ anchor('url-endpoints') }}URL Endpoints</h4>

      <p>
        <span class="term">The Company</span> may choose the root URL for their <span class="term">Server</span>.  The URLs defined here are relative to the root URL.  The <a class="attr-ref" href="#organization.sfin-url">sfin-url</a> attribute is the root URL.
      </p>

      {% macro urlsummary(method, url, whoitsfor) %}
      <dt class="url">
        {{ method }} {{ url }}
      </dt>
      <dd class="description">
        {{ caller() }}  This URL is used by the <span class="term">{{ whoitsfor }}</span>.
      </dd>
      {% endmacro %}

      {% call urlsummary('GET', '/auth', 'Browser' ) %}
        Returns an HTML page that the <span class="term">Account holder</span> can use to manage <span class="term">Access Tokens</span>.
      {% endcall %}

      {% call urlsummary('GET', '/accounts', 'Reader' ) %}
        Returns a list of available <a href="#account">Accounts</a>.
      {% endcall %}

      <p>
        Following are the details of each of the above URLs:
      </p>


      <div class="print-chunk">
        <h3 class="url">{{ anchor('/auth') }}GET /auth</h3>

        <p>
          This URL should land the <span class="term">Browser</span> on a web page that an <span class="term">Account holder</span> can use to generate and otherwise manage <span class="term">Setup tokens</span>.  The actual implementation of token management is up to <span class="term">The Company</span>.  However, please note the <a href="#recommendations">recommendations</a> below.
        </p>

        <p>
          <span class="term">Readers</span> will direct users to this URL if tokens are needed.  In your implementation, you can assume that a user visiting this URL wants to make a new token.
        </p>

        <p>
          <span class="term">Account holders</span> must be authenticated to access this page.  It is acceptable to redirect from this URL to
          another URL (in fact, we suspect that many <span class="term">Servers</span> will simply redirect the user to a different URL).
        </p>
      </div>
      
      <div class="print-chunk">
        <h3 class="url">{{ anchor('/accounts') }}GET /accounts</h3>

        <p>
          Returns an <a href="#account-set">Account Set</a> containing all accounts the requester is authorized to see.  This URL is intended
          for <span class="term">Readers</span>.
        </p>

        <ul class="std">
          <li>
            The <span class="code">Content-Type</span> of the response is always <span class="code">application/json</span>.
          </li>
          <li>
            If no query parameters are included in a request, then all the <a class="attr-ref" href="#account.transactions">Account.transactions</a> attributes will be empty lists.
          </li>
        </ul>
      </div>

      <div class="print-chunk">
        <h4>{{ anchor('authentication') }}Authentication</h4>

        <p>
          HTTP Bearer Authentication is used.  In every request, the client
          sends an <span class="code">Authentication</span> header of the format:
        </p>

        <div class="code-block">Authentication: Bearer ACCESS_TOKEN</div>

        <p>
          where <span class="code">ACCESS_TOKEN</span> is an <a href="#access-token">Access token</a>
        </p>
      </div>

      <h4>{{ anchor('accounts-query') }}Optional query parameters</h4>

      {% macro queryparam(name, examples) %}
      <div class="row-fluid query-param">
        <div class="span3 code">
          {{ anchor('accounts-query-'+name) }}{{ name }}
        </div>
        <div class="span9">
          <div class="description">{{ caller() }}</div>
          {% for example in examples %}
          <div class="example code-block">{{ example }}</div>
          {% endfor %}
        </div>
      </div>
      {% endmacro %}


      {% call queryparam('start-date', ['?start-date=989906400']) %}
        If given, transactions <em>on or after</em> the supplied timestamp will be included in the response.
      {% endcall %}

      {% call queryparam('end-date', []) %}
        If given, only transactions <em>before</em> the supplied date or timestamp will be returned.  Transactions with a <a class="attr-ref" href="#transaction.posted">posted</a> date equal to this date/timestamp will <em>not</em> be returned.

        For instance, querying for
        <div class="example code-block">?start-date=988696800&end-date=991375200</div>
        will return all transactions from May, 2001.
      {% endcall %}

      <div class="print-chunk">
        <h4>{{ anchor('accounts-sample-response') }}Sample response body</h4>

        <div class="code-block">{
  "accounts": [
    {
      "org": {
        "domain": "mybank.com",
        "sfin-url": "https://sfin.mybank.com"
        },
      "id": "2930002",
      "name": "Savings",
      "currency": "USD",
      "balance": "100.23",
      "available-balance": "75.23",
      "balance-date": 978366153,
    }
  ]
}</div>
      </div>

      <div class="print-chunk">
        <h4>{{ anchor('accounts-errors') }}Errors</h4>

        <p>
          Following are possible error responses:
        </p>

        {% macro error_response(code) %}
        <div class="row-fluid error-response">
          <div class="span3 code">
            {{ anchor('accounts-error-' + code) }}{{ code }}
          </div>
          <div class="span9">
            {{ caller() }}
          </div>
        </div>
        {% endmacro %}

        {% call error_response('403 Forbidden') %}
          If the requester is not authenticated or an invalid token is used.
        {% endcall %}

        {% call error_response('410 Gone') %}
          If <span class="url">start-date</span> specifies a date for which
          transaction data is no longer available (or was never available).
        {% endcall %}
      </div>

    </div>
  </div>

  {# comment #}
  <!--
  =============================================================================
  =============================================================================
  =============================================================================
  =============================================================================
  =============================================================================
  -->
  {# endcomment #}


  <div class="row-fluid section">
    <div class="content span8 offset2">

      <h2 class="no-page">{{ anchor('data-format') }}Data format</h2>

      <ul class="std">
        <li>Data is encoded as JSON strings.</li>
        <li>All attributes are required unless otherwise noted.</li>
        <li>All times are Unix epoch timestamps (long).</li>
      </ul>

      <p>
        These objects are defined by SimpleFIN (more details below):
      </p>

      <ul class="std">
        <li><a href="#organization">Organization</a></li>
        <li><a href="#account">Account</a></li>
        <li><a href="#transaction">Transaction</a></li>
        <li><a href="#account-set">Account Set</a></li>
      </ul>

      {% macro attribute(name, type, optional=False, object=None) %}
        <div class="attr-def">
          <div class="row-fluid">
            <div class="span3 attr-name">{% if object %}{{ anchor(object + '.' + name) }}{% endif %}{{ name }}</div>
            <div class="span9">
              <div><span class="attr-type">{{ type }}</span></div>
              {% if optional %}<div class="attr-optional">optional</div>{% endif %}
              <div class="attr-description">{{ caller('description') }}</div>
              {% if caller('example') %}
              <div class="attr-example code-block">{{ caller('example') }}</div>
              {% endif %}
            </div>
          </div>
        </div>
      {% endmacro %}

      <div class="object">
        <h3 class="object-name">{{ anchor('organization') }}Organization</h3>


        <div class="print-chunk">
          <h4>{{ anchor('organization-example') }}Example</h4>
          <div class="code-block">{
  "domain": "mybank.com",
  "sfin-url": "https://sfin.mybank.com"
}</div>
        </div>

        <h4>{{ anchor('organization-attributes') }}Attributes</h4>
        {% call(what) attribute('domain', 'string', object='organization') %}
          {%- if what == 'description' -%}
            The domain name of an organization with financial data.
          {%- elif what == 'example' -%}
            "example.com"
          {%- endif -%}
        {% endcall %}

        {% call(what) attribute('sfin-url', 'string', optional=True, object='organization') %}
          {%- if what == 'description' -%}
            URL of organization's SimpleFIN root endpoint.  If provided, the domain of the URL must match <a href="#organization.domain" class="attr-ref">domain</a>.
          {%- elif what == 'example' -%}
            "https://www.example.com/sfin"
          {%- endif -%}
        {% endcall %}

      </div>


      <div class="object">
        <div class="print-chunk">
          <h3 class="object-name">{{ anchor('account') }}Account</h3>

          <h4>{{ anchor('account-example') }}Example</h4>
          <div class="code-block">{
  "org": {
    "domain": "mybank.com",
    "sfin-url": "https://sfin.mybank.com"
  },
  "id": "2930002",
  "name": "Savings",
  "currency": "USD",
  "balance": "100.23",
  "available-balance": "75.23",
  "balance-date": 978366153,
  "transactions": [
    {
      "id": "AO334",
      "posted": 793090572,
      "amount": "-33293.43",
      "description": "Uncle Frank's Bait Shop",
    }
  ]
}</div>
        </div>

          <h4>{{ anchor('account-attributes') }}Attributes</h4>
          {% call(what) attribute('org', '<a href="#organization">Organization</a>', object='account') %}
            {%- if what == 'description' -%}
              Organization from which
              this account originates.  If this is a bank account,
              this field will be the bank's organization.
            {%- elif what == 'example' -%}
{
  "domain": "example.com",
  "sfin-url": "https://www.example.com/sfin"
}
            {%- endif -%}
          {% endcall %}

          {% call(what) attribute('id', 'string', object='account') %}
            {%- if what == 'description' -%}
              An ID that uniquely identifies an account within the
              account's organization.  It is recommended that this
              id be chosen such that it does not reveal
              any sensitive data (login information for the bank's
              web banking portal, for instance).
            {%- elif what == 'example' -%}"123"{%- endif -%}
          {% endcall %}

          {% call(what) attribute('name', 'string', object='account') %}
            {%- if what == 'description' -%}
              A name that uniquely describes an account among all the
              users other accounts.
              This name should be chosen so that a person can easily associate
              it with only one of their accounts within an organization.
            {%- elif what == 'example' -%}"Money-Market Checking"{%- endif -%}
          {% endcall %}

          {% call(what) attribute('currency', 'string', object='account') %}
            {%- if what == 'description' -%}
            <p>
              If the currency is a standard currency, use the currency code from the <a href="http://www.iso.org/iso/home/standards/currency_codes.htm" target="_blank">official ISO 4217</a> (or see <a href="http://en.wikipedia.org/wiki/ISO_4217" target="_blank">the Wikipedia article</a>)  For example:
            </p>

            <div class="attr-example code-block">"ZMW"</div>
            <div class="attr-example code-block">"GBP"</div>

            <p>
              Custom/proprietary currencies are also supported.  For instance, rewards points or frequent flier miles are a type of "currency."  To indicate a custom currency supply a URL as the value.  For example:
            </p>

            <div class="attr-example code-block">"https://www.example.com/currency/rewardpoints"</div>

            <p>
              Making an unauthenticated <span class="url">GET</span> request to the URL should return an <span class="url">application/json</span> response representing an object with at least a <span class="attr-ref">name</span> attribute with a human-readable string name for the currency as the value.  For example, here is an acceptable response:
            </p>

            <div class="attr-example code-block">{ "name": "Reward Points" }</div>

            {%- endif -%}
          {% endcall %}

          {% call(what) attribute('balance', 'numeric string', object='account') %}
            {%- if what == 'description' -%}
              The balance of the account as of
              <a class="attr-ref" href="#account.balance-date">balance-date</a>.
            {%- elif what == 'example' -%}"22.33"{%- endif -%}
          {% endcall %}

          {% call(what) attribute('available-balance', 'numeric string', optional=True, object='account') %}
            {%- if what == 'description' -%}
              The available balance of the account as of
              <a class="attr-ref" href="#account.balance-date">balance-date</a>.  This
              may be omitted if it is the same as <a class="attr-ref" href="#account.balance">balance</a>.
            {%- elif what == 'example' -%}"15.33"{%- endif -%}
          {% endcall %}

          {% call(what) attribute('balance-date', 'UNIX epoch timestamp', object='account') %}
            {%- if what == 'description' -%}
            <p>
              The timestamp when the <a class="attr-ref" href="#account.balance">balance</a> and <a class="attr-ref" href="#account.available-balance">available-balance</a> became what they are.
            </p>
            {%- elif what == 'example' -%}
              978366153
            {%- endif -%}
          {% endcall %}

          {% call(what) attribute('transactions', 'list of <a href="#transaction">Transactions</a>', optional=True, object='account') %}
            {%- if what == 'description' -%}
              List of a subset of <a href="#transaction">Transactions</a> for
              this account, ordered by <a class="attr-ref" href="#transaction.posted">posted</a>.
            {%- elif what == 'example' -%}
[{
  "id": "AO334",
  "posted": 978366153,
  "amount": "-22.33",
  "memo": "John's Pizza Pie Cafe and Spa",
}]
            {%- endif -%}
          {% endcall %}

          {% call(what) attribute('extra', 'object', optional=True, object='account') %}
            {%- if what == 'description' -%}
              This optional attribute may be used to include extra account-specific data that is not defined in this standard.  It is up to the <a href="#server" class="term">Server</a> to decide whether or not to include data in here.
            {%- elif what == 'example' -%}
{
  "account_open_date": 958284000
}
            {%- endif -%}
          {% endcall %}

        </div>

        <div class="object">
          <div class="print-chunk">
            <h3>{{ anchor('transaction') }}Transaction</h3>
          
            <h4>{{ anchor('transaction-example') }}Example</h4>

            <div class="code-block">{
  "id": "12394832938403",
  "posted": 793090572,
  "amount": "-33293.43",
  "description": "Uncle Frank's Bait Shop",
}</div>
          </div>


          <h4>{{ anchor('transaction-attributes') }}Attributes</h4>

          {% call(what) attribute('id', 'string', object='transaction') %}
            {%- if what == 'description' -%}
              An ID that uniquely describes a transaction within an
              Account.  An organization may reuse transaction ids
              for different accounts, but may never reuse a
              transaction id within an account.
            {%- elif what == 'example' -%}
              "9990203-3840394"
            {%- endif -%}
          {% endcall %}

          {% call(what) attribute('posted', 'UNIX epoch timestamp', object='transaction') %}
            {%- if what == 'description' -%}
              This is when the transaction happened.
              The timezone must be GMT.
            {%- elif what == 'example' -%}
              1420131603
            {%- endif -%}
          {% endcall %}

          {% call(what) attribute('amount', 'numeric string', object='transaction') %}
            {%- if what == 'description' -%}
              Amount of transaction.  Positive numbers indicate money
              being deposited into the account.
            {%- elif what == 'example' -%}
              "90.28"
            {%- endif -%}
          {% endcall %}

          {% call(what) attribute('description', 'string', object='transaction') %}
            {%- if what == 'description' -%}
              A human-readable description of what the transaction was for.
            {%- elif what == 'example' -%}
              "Bob's Grocery Store - 22 S. Main"
            {%- endif -%}
          {% endcall %}

          {% call(what) attribute('extra', 'object', optional=True, object='transaction') %}
            {%- if what == 'description' -%}
              This optional attribute may be used to include extra transaction-specific data that is not defined in this standard.  It is up to the <a href="#server" class="term">Server</a> to decide whether or not to include data in here.
            {%- elif what == 'example' -%}
{
  "sic": "2839"
}
            {%- endif -%}
          {% endcall %}

        </div>

        <div class="object">

          <div class="print-chunk">
            <h3>{{ anchor('account-set') }}Account Set</h3>
          
            <h4>{{ anchor('account-set-example') }}Example</h4>

            <div class="code-block">{
  "accounts": [
    {
      "org": {
        "domain": "mybank.com",
        "sfin-url": "https://sfin.mybank.com"
      },
      "id": "2930002",
      "name": "Savings",
      "currency": "USD",
      "balance": "100.23",
      "available-balance": "75.23",
      "balance-date": 978366153,
      "transactions": []
    }
  ]
}</div>
          </div>

          <h4>{{ anchor('account-set-attributes') }}Attributes</h4>

          {% call(what) attribute('accounts', 'list of <a href="#account">Accounts</a>', object='account-set') %}
            {%- if what == 'description' -%}
              A list of <a class="attr-ref" href="#account">Account</a> objects.  Order does not matter.
            {%- elif what == 'example' -%}
            {%- endif -%}
          {% endcall %}
        </div>
    </div>
  </div>

  <div class="row-fluid section">
    <div class="content span8 offset2">

      <h2>{{ anchor('recommendations') }}Recommendations</h2>

      <p>
        It is <em>recommended</em> that <span class="term">Account holders</span> have the following abilities regarding token management:
      </p>

      <ol class="std">
        <li>
          Users can associate user-provided names with tokens (e.g. "This is the token being used by example.com").
        </li>
        <li>
          Users can create many tokens (for providing to multiple third party services).
        </li>
        <li>
          Users can choose an expiration date for tokens when creating them.
        </li>
        <li>
          Users can manually invalidate/expire existing tokens at
          will.  This is useful in the case of stolen tokens or abuse
          by third parties to whom tokens were given.
        </li>
      </ol>

      <p>
        Additionally, consider the following when implementing a token
        management system:
      </p>

      <ol class="std">
        <li>
          It may be nice to notify users prior to token expiration.
        </li>
        <li>
          It may be nice to allow users to temporarily disable all tokens and later re-enable them.  This can be used to prevent access while doing research into abuse.
        </li>
        <li>
          Consider providing logging/audit information regarding token use, including the time tokens were used and the IPs from which requests came.
        </li>
        <li>
          Allow tokens to be associated with a subset of available accounts.  For instance, allow the user to create one token for access to just their checking account, and another token for access to just their savings account.
        </li>
      </ol>

    </div>
  </div>
</div>

{% endblock %}