diff --git a/bin/build-apidocs.sh b/bin/build-apidocs.sh
index be85012c..97b73cda 100755
--- a/bin/build-apidocs.sh
+++ b/bin/build-apidocs.sh
@@ -2,8 +2,13 @@
 
 # Note: you need to run `npm install` before using this script or raml2html won't be installed
 
+OLD_DIR=$(pwd)
+cd $(dirname $0)/..
+
 if [[ ! -x ./node_modules/.bin/raml2html ]]; then
   npm install
 fi
 
-./node_modules/.bin/raml2html -i ./doc/api/api.raml -o ./public/api/index.html
+./node_modules/.bin/raml2html -i ./doc/api/api.raml -o ./public/api/index.html -t doc/api/templates/template.nunjucks
+
+cd $OLD_DIR
diff --git a/doc/api/api.raml b/doc/api/api.raml
index f5402db7..c2382ea2 100644
--- a/doc/api/api.raml
+++ b/doc/api/api.raml
@@ -13,7 +13,9 @@ documentation:
 
 securitySchemes:
   oauth_2_0: !include securitySchemes/oauth_2_0.raml
-securedBy: [ null, cookie, token, oauth_2_0 ]
+  token: !include securitySchemes/token.raml
+  cookie: !include securitySchemes/cookie.raml
+securedBy: [ token, cookie, oauth_2_0 ]
 
 traits:
   pageable: !include traits/pageable.raml
diff --git a/doc/api/securitySchemes/cookie.raml b/doc/api/securitySchemes/cookie.raml
new file mode 100644
index 00000000..4e1723a9
--- /dev/null
+++ b/doc/api/securitySchemes/cookie.raml
@@ -0,0 +1,3 @@
+description: Cookie-based authentication
+type: x-cookie
+displayName: Cookie
diff --git a/doc/api/securitySchemes/oauth_2_0.raml b/doc/api/securitySchemes/oauth_2_0.raml
index 6f23ae02..2e857983 100644
--- a/doc/api/securitySchemes/oauth_2_0.raml
+++ b/doc/api/securitySchemes/oauth_2_0.raml
@@ -1,4 +1,4 @@
-description: !include ../pages/oauth_tutorial.md
+description: Secured by OAuth 2.0
 type: OAuth 2.0
 settings:
   authorizationUri: https://metamaps.cc/api/v2/oauth/authorize
diff --git a/doc/api/securitySchemes/token.raml b/doc/api/securitySchemes/token.raml
new file mode 100644
index 00000000..8cbd5258
--- /dev/null
+++ b/doc/api/securitySchemes/token.raml
@@ -0,0 +1,3 @@
+description: Token-based authenticationSecured by OAuth 2.0
+type: x-token
+displayName: Token-based auth
diff --git a/doc/api/templates/item.nunjucks b/doc/api/templates/item.nunjucks
new file mode 100644
index 00000000..044c24d9
--- /dev/null
+++ b/doc/api/templates/item.nunjucks
@@ -0,0 +1,61 @@
+<li>
+  {% if item.displayName %}
+    <strong>{{ item.displayName }}</strong>:
+  {% else %}
+    <strong>{{ item.key }}</strong>:
+  {% endif %}
+
+  {% if not item.structuredValue %}
+    <em>
+      {%- if item.required -%}required {% endif -%}
+      (
+      {%- if item.enum -%}
+        {%- if item.enum.length === 1 -%}
+          {{ item.enum.join(', ') }}
+        {%- else -%}
+          one of {{ item.enum.join(', ') }}
+        {%- endif -%}
+      {%- else -%}
+        {{ item.type }}
+      {%- endif -%}
+
+      {%- if item.default or item.default == 0 or item.default == false %} - default: {{ item.default }}{%- endif -%}
+      {%- if item.repeat %} - repeat: {{ item.repeat }}{%- endif -%}
+      {%- if item.type == 'string' -%}
+        {%- if item.minLength or item.minLength == 0 %} - minLength: {{ item.minLength }}{%- endif -%}
+        {%- if item.maxLength or item.maxLength == 0 %} - maxLength: {{ item.maxLength }}{%- endif -%}
+      {%- else -%}
+        {%- if item.minimum or item.minimum == 0 %} - minimum: {{ item.minimum }}{%- endif -%}
+        {%- if item.maximum or item.maximum == 0 %} - maximum: {{ item.maximum }}{%- endif -%}
+      {%- endif -%}
+      {%- if item.pattern %} - pattern: {{ item.pattern }}{%- endif -%}
+      )
+    </em>
+  {% endif %}
+
+{% markdown %}
+{{ item.description }}
+{% endmarkdown %}
+
+{#
+  {% if item.type %}
+    <p><strong>Type</strong>:</p>
+    <pre><code>{{ item.type | escape }}</code></pre>
+  {% endif %}
+#}
+
+  {% if item.examples.length %}
+    <p><strong>Examples</strong>:</p>
+    {% for example in item.examples %}
+      {% if item.type == 'string' %}
+        <pre>{{ example | escape }}</pre>
+      {% else %}
+        <pre><code>{{ example | escape }}</code></pre>
+      {% endif %}
+    {% endfor %}
+  {% endif %}
+
+  {% if item.structuredValue %}
+    <pre><code>{{ item.structuredValue | dump }}</code></pre>
+  {% endif %}
+</li>
diff --git a/doc/api/templates/resource.nunjucks b/doc/api/templates/resource.nunjucks
new file mode 100644
index 00000000..66fb466c
--- /dev/null
+++ b/doc/api/templates/resource.nunjucks
@@ -0,0 +1,293 @@
+{% if (resource.methods or (resource.description and resource.parentUrl)) %}
+  <div class="panel panel-white">
+    <div class="panel-heading">
+      <h4 class="panel-title">
+        <a class="collapsed" data-toggle="collapse" href="#panel_{{ resource.uniqueId }}">
+          <span class="parent">{{ resource.parentUrl }}</span>{{ resource.relativeUri }}
+        </a>
+
+        <span class="methods">
+          {% for method in resource.methods %}
+            <a href="#{{ resource.uniqueId }}_{{ method.method }}"><!-- modal shown by hashchange event -->
+              <span class="badge badge_{{ method.method }}">{{ method.method }}{% if method.securedBy.length %} <span class="glyphicon glyphicon-lock" title="Authentication required"></span>{% endif %}</span>
+            </a>
+          {% endfor %}
+        </span>
+      </h4>
+    </div>
+
+    <div id="panel_{{ resource.uniqueId }}" class="panel-collapse collapse">
+      <div class="panel-body">
+        {% if resource.parentUrl %}
+          {% if resource.description %}
+            <div class="resource-description">
+{% markdown %}
+{{ resource.description }}
+{% endmarkdown %}
+            </div>
+          {% endif %}
+        {% endif %}
+
+        <div class="list-group">
+          {% for method in resource.methods %}
+            <div onclick="window.location.href = '#{{ resource.uniqueId }}_{{ method.method }}'" class="list-group-item">
+              <span class="badge badge_{{ method.method }}">{{ method.method }}{% if method.securedBy.length %} <span class="glyphicon glyphicon-lock" title="Authentication required"></span>{% endif %}</span>
+              <div class="method_description">
+{% markdown %}
+{{ method.description}}
+{% endmarkdown %}
+              </div>
+              <div class="clearfix"></div>
+            </div>
+          {% endfor %}
+        </div>
+      </div>
+    </div>
+
+    {% for method in resource.methods %}
+      <div class="modal fade" tabindex="0" id="{{ resource.uniqueId }}_{{ method.method }}">
+        <div class="modal-dialog">
+          <div class="modal-content">
+            <div class="modal-header">
+              <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
+              <h4 class="modal-title" id="myModalLabel">
+                <span class="badge badge_{{ method.method }}">{{ method.method }}{% if method.securedBy.length %} <span class="glyphicon glyphicon-lock" title="Authentication required"></span>{% endif %}</span>
+                <span class="parent">{{ resource.parentUrl }}</span>{{ resource.relativeUri }}
+              </h4>
+            </div>
+
+            <div class="modal-body">
+              {% if method.description %}
+                <div class="alert alert-info">
+{% markdown %}
+{{ method.description}}
+{% endmarkdown %}
+                </div>
+              {% endif %}
+
+              {% if method.securedBy.length %}
+                {% for securedBy in method.securedBy %}
+                  {% if securedBy %}
+                    <div class="alert alert-warning">
+                      {% set securedByScopes = renderSecuredBy(securedBy) %}
+                      <span class="glyphicon glyphicon-lock" title="Authentication required"></span> Secured by {{ securedByScopes }}
+                      {% set securityScheme = securitySchemes[securedBy] %}
+                      {% if securityScheme.description %}
+{% markdown %}
+{{ securityScheme.description }}
+{% endmarkdown %}
+                      {% endif %}
+                    </div>
+                  {% endif %}
+                {% endfor %}
+              {% endif %}
+
+              <!-- Nav tabs -->
+              <ul class="nav nav-tabs">
+                {% if method.allUriParameters.length or method.queryString or method.queryParameters or method.headers or method.body %}
+                  <li class="active">
+                    <a href="#{{ resource.uniqueId }}_{{ method.method }}_request" data-toggle="tab">Request</a>
+                  </li>
+                {% endif %}
+
+                {% if method.responses %}
+                  <li{%
+                    if not method.allUriParameters.length and not method.queryParameters
+                    and not method.queryString
+                    and not method.headers and not method.body
+                    %} class="active"{%
+                    endif
+                    %}>
+                    <a href="#{{ resource.uniqueId }}_{{ method.method }}_response" data-toggle="tab">Response</a>
+                  </li>
+                {% endif %}
+
+                {% if method.securedBy.length %}
+                  <li>
+                    <a href="#{{ resource.uniqueId }}_{{ method.method }}_securedby" data-toggle="tab">Security</a>
+                  </li>
+                {% endif %}
+              </ul>
+
+              <!-- Tab panes -->
+              <div class="tab-content">
+                {% if method.allUriParameters.length or method.queryString or method.queryParameters or method.headers or method.body %}
+                  <div class="tab-pane active" id="{{ resource.uniqueId }}_{{ method.method }}_request">
+                    {% if resource.allUriParameters.length %}
+                      <h3>URI Parameters</h3>
+                      <ul>
+                        {% for item in resource.allUriParameters %}
+                          {% include "./item.nunjucks" %}
+                        {% endfor %}
+                      </ul>
+                    {% endif %}
+
+                    {% if method.annotations.length %}
+                      <h3>Annotations</h3>
+                      <ul>
+                        {% for item in method.annotations %}
+                          {% include "./item.nunjucks" %}
+                        {% endfor %}
+                      </ul>
+                    {% endif %}
+
+                    {% if method.headers.length %}
+                      <h3>Headers</h3>
+                      <ul>
+                        {% for item in method.headers %}
+                          {% include "./item.nunjucks" %}
+                        {% endfor %}
+                      </ul>
+                    {% endif %}
+
+                    {% if method.queryString and method.queryString.properties.length %}
+                      <h3>Query String</h3>
+                      <ul>
+                        {% for item in method.queryString.properties %}
+                          {% include "./item.nunjucks" %}
+                        {% endfor %}
+                      </ul>
+                    {% endif %}
+
+                    {% if method.queryParameters.length %}
+                      <h3>Query Parameters</h3>
+                      <ul>
+                        {% for item in method.queryParameters %}
+                          {% include "./item.nunjucks" %}
+                        {% endfor %}
+                      </ul>
+                    {% endif %}
+
+                    {% if method.body %}
+                      <h3>Body</h3>
+                      {% for b in method.body %}
+                        <p><strong>Type: {{ b.key }}</strong></p>
+
+{#
+                        {% if b.type %}
+                          <p><strong>Type</strong>:</p>
+                          <pre><code>{{ b.type | escape }}</code></pre>
+                        {% endif %}
+#}
+
+                        {% if b.properties.length %}
+                          <strong>Properties</strong>
+                          <ul>
+                            {% for item in b.properties %}
+                              {% include "./item.nunjucks" %}
+                            {% endfor %}
+                          </ul>
+                        {% endif %}
+
+                        {% if b.examples.length %}
+                          <p><strong>Examples</strong>:</p>
+                          {% for example in b.examples %}
+                            <pre><code>{{ example | escape }}</code></pre>
+                          {% endfor %}
+                        {% endif %}
+                      {% endfor %}
+                    {% endif %}
+                  </div>
+                {% endif %}
+
+                {% if method.responses %}
+                  <div class="tab-pane{%
+                    if not method.allUriParameters.length and not method.queryParameters.length
+                    and not method.queryString
+                    and not method.headers.length and not method.body.length
+                    %} active{%
+                    endif
+                    %}" id="{{ resource.uniqueId }}_{{ method.method }}_response">
+                    {% for response in method.responses %}
+                      <h2>HTTP status code <a href="http://httpstatus.es/{{ response.code }}" target="_blank">{{ response.code }}</a></h2>
+{% markdown %}
+{{ response.description}}
+{% endmarkdown %}
+
+                      {% if response.headers.length %}
+                        <h3>Headers</h3>
+                        <ul>
+                          {% for item in response.headers %}
+                            {% include "./item.nunjucks" %}
+                          {% endfor %}
+                        </ul>
+                      {% endif %}
+
+                      {% if response.body.length %}
+                        <h3>Body</h3>
+                        {% for b in response.body %}
+                          <p><strong>Type: {{ b.key }}</strong></p>
+
+{#
+                          {% if b.type %}
+                            <p><strong>Type</strong>:</p>
+                            <pre><code>{{ b.type | escape }}</code></pre>
+                          {% endif %}
+#}
+
+                          {% if b.properties.length %}
+                            <strong>Properties</strong>
+                            <ul>
+                              {% for item in b.properties %}
+                                {% include "./item.nunjucks" %}
+                              {% endfor %}
+                            </ul>
+                          {% endif %}
+
+                          {% if b.examples.length %}
+                            <p><strong>Examples</strong>:</p>
+                            {% for example in b.examples %}
+                              <pre><code>{{ example | escape }}</code></pre>
+                            {% endfor %}
+                          {% endif %}
+                        {% endfor %}
+                      {% endif %}
+                    {% endfor %}
+                  </div>
+                {% endif %}
+
+                {% if method.securedBy.length %}
+                  <div class="tab-pane" id="{{ resource.uniqueId }}_{{ method.method }}_securedby">
+                    {% for securedBy in method.securedBy %}
+                      {% set securityScheme = securitySchemes[securedBy] %}
+                      <h1>Secured by {{ securedBy }}</h1>
+
+                      {% if securityScheme.describedBy.headers.length %}
+                        <h3>Headers</h3>
+                        <ul>
+                          {% for item in securityScheme.describedBy.headers %}
+                            {% include "./item.nunjucks" %}
+                          {% endfor %}
+                        </ul>
+                      {% endif %}
+
+                      {% for response in securityScheme.describedBy.responses.length %}
+                        <h2>HTTP status code <a href="http://httpstatus.es/{{ response.code }}" target="_blank">{{ response.code }}</a></h2>
+{% markdown %}
+{{ response.description}}
+{% endmarkdown %}
+                        {% if response.headers.length %}
+                          <h3>Headers</h3>
+                          <ul>
+                            {% for item in response.headers %}
+                              {% include "./item.nunjucks" %}
+                            {% endfor %}
+                          </ul>
+                        {% endif %}
+                      {% endfor %}
+
+                    {% endfor %}
+                  </div>
+                {% endif %}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    {% endfor %}
+  </div>
+{% endif %}
+
+{% for resource in resource.resources %}
+  {% include "./resource.nunjucks" %}
+{% endfor %}
diff --git a/doc/api/templates/template.nunjucks b/doc/api/templates/template.nunjucks
new file mode 100644
index 00000000..6911f44e
--- /dev/null
+++ b/doc/api/templates/template.nunjucks
@@ -0,0 +1,232 @@
+<!DOCTYPE HTML>
+<html>
+  <head>
+    <title>{{ title }} API documentation</title>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <meta name="generator" content="https://github.com/raml2html/raml2html {{ config.raml2HtmlVersion }}">
+
+    <link rel="stylesheet" href="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.3.0/styles/default.min.css">
+    <script type="text/javascript" src="https://code.jquery.com/jquery-1.11.0.min.js"></script>
+    <script type="text/javascript" src="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
+    <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.3.0/highlight.min.js"></script>
+
+    <script type="text/javascript">
+      $(document).ready(function() {
+        $('.page-header pre code, .top-resource-description pre code, .modal-body pre code').each(function(i, block) {
+          hljs.highlightBlock(block);
+        });
+
+        $('[data-toggle]').click(function() {
+          var selector = $(this).data('target') + ' pre code';
+          $(selector).each(function(i, block) {
+            hljs.highlightBlock(block);
+          });
+        });
+
+        // open modal on hashes like #_action_get
+        $(window).bind('hashchange', function(e) {
+          var anchor_id = document.location.hash.substr(1); //strip #
+          var element = $('#' + anchor_id);
+
+          // do we have such element + is it a modal?  --> show it
+          if (element.length && element.hasClass('modal')) {
+            element.modal('show');
+          }
+        });
+
+        // execute hashchange on first page load
+        $(window).trigger('hashchange');
+
+        // remove url fragment on modal hide
+        $('.modal').on('hidden.bs.modal', function() {
+          try {
+            if (history && history.replaceState) {
+                history.replaceState({}, '', '#');
+            }
+          } catch(e) {}
+        });
+      });
+    </script>
+
+    <style>
+      .hljs {
+        background: transparent;
+      }
+      .parent {
+        color: #999;
+      }
+      .list-group-item > .badge {
+        float: none;
+        margin-right: 6px;
+      }
+      .panel-title > .methods {
+        float: right;
+      }
+      .badge {
+        border-radius: 0;
+        text-transform: uppercase;
+        width: 70px;
+        font-weight: normal;
+        color: #f3f3f6;
+        line-height: normal;
+      }
+      .badge_get {
+        background-color: #63a8e2;
+      }
+      .badge_post {
+        background-color: #6cbd7d;
+      }
+      .badge_put {
+        background-color: #22bac4;
+      }
+      .badge_delete {
+        background-color: #d26460;
+      }
+      .badge_patch {
+        background-color: #ccc444;
+      }
+      .list-group, .panel-group {
+        margin-bottom: 0;
+      }
+      .panel-group .panel+.panel-white {
+        margin-top: 0;
+      }
+      .panel-group .panel-white {
+        border-bottom: 1px solid #F5F5F5;
+        border-radius: 0;
+      }
+      .panel-white:last-child {
+        border-bottom-color: white;
+        -webkit-box-shadow: none;
+        box-shadow: none;
+      }
+      .panel-white .panel-heading {
+        background: white;
+      }
+      .tab-pane ul {
+        padding-left: 2em;
+      }
+      .tab-pane h1 {
+        font-size: 1.3em;
+      }
+      .tab-pane h2 {
+        font-size: 1.2em;
+        padding-bottom: 4px;
+        border-bottom: 1px solid #ddd;
+      }
+      .tab-pane h3 {
+        font-size: 1.1em;
+      }
+      .tab-content {
+        border-left: 1px solid #ddd;
+        border-right: 1px solid #ddd;
+        border-bottom: 1px solid #ddd;
+        padding: 10px;
+      }
+      #sidebar {
+        margin-top: 30px;
+        padding-right: 5px;
+        overflow: auto;
+        height: 90%;
+      }
+      .top-resource-description {
+        border-bottom: 1px solid #ddd;
+        background: #fcfcfc;
+        padding: 15px 15px 0 15px;
+        margin: -15px -15px 10px -15px;
+      }
+      .resource-description {
+        border-bottom: 1px solid #fcfcfc;
+        background: #fcfcfc;
+        padding: 15px 15px 0 15px;
+        margin: -15px -15px 10px -15px;
+      }
+      .resource-description p:last-child {
+        margin: 0;
+      }
+      .list-group .badge {
+        float: left;
+      }
+      .method_description {
+        margin-left: 85px;
+      }
+      .method_description p:last-child {
+        margin: 0;
+      }
+      .list-group-item {
+        cursor: pointer;
+      }
+      .list-group-item:hover {
+        background-color: #f5f5f5;
+      }
+
+      pre code {
+        overflow: auto;
+        word-wrap: normal;
+        white-space: pre;
+      }
+    </style>
+  </head>
+
+  <body data-spy="scroll" data-target="#sidebar">
+    <div class="container">
+      <div class="row">
+        <div class="col-md-9" role="main">
+          <div class="page-header">
+            <h1>{{ title }} API documentation{% if version %} <small>version {{ version }}</small>{% endif %}</h1>
+            <p>{{ baseUri }}</p>
+
+            {% if baseUriParameters %}
+              <ul>
+                {% for item in baseUriParameters %}
+                  {% include "./item.nunjucks" %}
+                {% endfor %}
+              </ul>
+            {% endif %}
+          </div>
+
+          {% for resource in resources %}
+            <div class="panel panel-default">
+              <div class="panel-heading">
+                <h3 id="{{ resource.uniqueId }}" class="panel-title">{% if resource.displayName %}{{ resource.displayName}}{% else %}{{ resource.relativeUri }}{% endif %}</h3>
+              </div>
+
+              <div class="panel-body">
+                {% if resource.description %}
+                  <div class="top-resource-description">
+{% markdown %}
+{{ resource.description }}
+{% endmarkdown %}
+                  </div>
+                {% endif %}
+
+                <div class="panel-group">
+                  {% include "./resource.nunjucks" %}
+                </div>
+              </div>
+            </div>
+          {% endfor %}
+
+            {% for chapter in documentation %}
+              <h3 id="{{ chapter.uniqueId }}"><a href="#{{ chapter.uniqueId }}">{{ chapter.title }}</a></h3>
+{% markdown %}
+{{ chapter.content }}
+{% endmarkdown %}
+            {% endfor %}
+        </div>
+
+        <div class="col-md-3">
+          <div id="sidebar" class="hidden-print affix" role="complementary">
+            <ul class="nav nav-pills nav-stacked">
+              {% for resource in resources %}
+                <li><a href="#{{ resource.uniqueId}}">{% if resource.displayName %}{{ resource.displayName}}{% else %}{{ resource.relativeUri }}{% endif %}</a></li>
+              {% endfor %}
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+  </body>
+</html>