Signed maps

Signed maps are layergroup configurations (or templates) that are granted permission to access the database on the behalf of CartoDB users other than the one logged in at usage time.

Signing a map

Any CartoDB users may sign any layergroup configuration and optionally specify an authorization method that a web user would be required to pass in order to use the grant.

Layergroup configurations are identified by their layergroup_id token, as returned by POST-ing the full configuration to the Windshaft layergroup entry point (https://github.com/CartoDB/Windshaft/wiki/Multilayer-API). Note that the layergroup_id token does not include the last_modified component.

Authorization methods

Open authorization

With this kind of authorization anyone can use the map on the signing user behalf

Token based authorization

With this authorization type, web users willing to use the map on behalf of the signing CartoDB user would need to provide any of those tokens.

Example API for signing a map

Signing a layergroup configuration could involve POST-ing a signature certificate:

// signature.json
{
  version: '0.0.1',
  layergroup_id: 'c01a54877c62831bb51720263f91fb33',
  // layergroup_template_id: '...' // for templated maps
  auth {
   method: 'token', // or "open" (the default if no "method" is given)
   valid_tokens: ['auth_token1','auth_token2']
  }
}

Signing as the user authenticated with APIKEY:

curl 'https://docs.cartodb.com/tiles/layergroup/sign?api_key=APIKEY' -d @signature.json

Using a signed map

When fetching tiles or grids from a map, a web user may reference a "signing" CartoDB user to request that the database access occurs in her behalf, eventually providing the required authorization information.

Example API for fetching a tile

Fetching tiles from a map signed by CartoDB user "docs" could be done like this:

curl 'https://docs.cartodb.com/tiles/layergroup/docs@c01a54877c62831bb51720263f91fb33:1234/0/0/0.png?auth_token=auth_token2'

NOTE: I'm not sure I like embedding the signer name in the "layergroup_token" component in the URL above, to reduce confusion it could be a different url component...

Note that the same tile could be fetched without requesting special privileges with a normal call:

curl 'https://docs.cartodb.com/tiles/layergroup/c01a54877c62831bb51720263f91fb33:1234/0/0/0.png'

Signatures management

Signatures are persistent. Owners can create or delete them. Multiple signatures for the same resource are allowed, even from the same owner.

Operations against signatures

Operations required, and their frequency

operation	when	freq.
Get all signatures by user Y on resource X	get signed token	high
Delete a specific signature	del tpl / upd sig	low
Del all signatures on instance of template T	del template	low
Sign resource X	create signed map	low
Get all signatures by user Y	manage signatures	low