Authentication

SlicingDice's REST API supports authentication through API keys for the team or the database you want to use, representing the required credentials for a given operation.


API Base URL

The base URL used for executing API requests is https://api.slicingdice.com/v1/{endpoint}


API Request Header

HTTP headers are required in order to interact with the API. All requests must contain:

  • An Authorization header with a valid Team Key or a Database Key
  • A Content-Type header informing the content type used on the request (application/json or application/sql)
$ curl -X GET https://api.slicingdice.com/v1/query/count/entity/total \
    -H 'Authorization: DATABASE_OR_TEAM_KEY' \
    -H 'Content-Type: application/json'
from pyslicer import SlicingDice
slicingdice = SlicingDice(master_key='DATABASE_OR_TEAM_KEY', uses_test_endpoint=True)

print(slicingdice.count_entity_total())
import com.slicingdice.jslicer.SlicingDice;
import java.io.IOException;
import org.json.JSONObject;
import org.json.JSONArray;

public class Example {
    public static void main(String[] args) throws IOException {
        SlicingDice slicingdice = new SlicingDice("DATABASE_OR_TEAM_KEY", true);

        JSONObject result = slicingdice.countEntityTotal();
        System.out.println(result.toString());
    }
}
require 'rbslicer'
slicingdice = SlicingDice.new(master_key: 'DATABASE_OR_TEAM_KEY', uses_test_endpoint: true)

puts slicingdice.count_entity_total()
const SlicingDice = require('slicerjs');

const usesTestEndpoint = true;
const slicingdice = new SlicingDice({masterKey: 'DATABASE_OR_TEAM_KEY'}, usesTestEndpoint);

slicingdice.countEntityTotal().then((resp) => {
    console.log(resp);
}, (err) => {
    console.error(err);
});
<?php
use Slicer\SlicingDice;
$usesTestEndpoint = true;
$slicingdice = new SlicingDice(array("masterKey" => "DATABASE_OR_TEAM_KEY"), $usesTestEndpoint);

print_r($slicingdice->countEntityTotal());
?>
using System.Collections.Generic;
using Slicer;
using Newtonsoft.Json;

namespace SlicerTester.Console
{
    class Program
    {
        static void Main(string[] args)
        {
            var slicingdice = new SlicingDice(masterKey: "DATABASE_OR_TEAM_KEY", usesTestEndpoint: true);

            var result = slicingdice.CountEntityTotal();
            System.Console.WriteLine(JsonConvert.SerializeObject(result).ToString());
        }
    }
}
package main
import (
    "fmt"
    "github.com/SlicingDice/slicingdice-go/slicingdice"
)
func main() {
    keys := new(slicingdice.APIKey)
    keys.MasterKey = "DATABASE_OR_TEAM_KEY"
    slicingdice := slicingdice.New(keys, 60)
    slicingdice.Test = true

    fmt.Println(slicingdice.CountEntityTotal())
}

Team Key

The Team Key is an API key associated with the entire team of your account and it's automatically created when the first user of a team sign up. Just this administrator user has access to this key.

The following endpoints can be accessed by this key through the HTTP methods shown below:

Endpoint HTTP Methods Description
/database POST
PUT
DEL
  • Create a new database
  • Update a database
  • Delete a database
/database/retrieve_all GET
  • Retrieve all databases and their information
/database/custom_key POST
PUT
DEL
GET
  • Create a custom key
  • Update a custom key
  • Delete a custom key
  • Retrieve all custom keys and their information
/users POST
PUT
DEL
GET
  • Create an user
  • Update an user
  • Deactivate an user
  • Retrieve all registered users
/permission_groups POST
PUT
DEL
GET
  • Create a permission group
  • Update a permission group
  • Delete a permission group
  • Retrieve all registered permission groups

Team Key Permissions

You can modify the permissions of a Team API Key while retrieving it in order to prevent wrong operations, like deleting databases. These are the permissions you can set:

  • List: define if this key can list Databases, Permission Groups, Users and Custom Keys
  • Update: define if this key can update Databases, Permission Groups, Users and Custom Keys
  • Delete: define if this key can delete Databases, Permission Groups, Users and Custom Keys

Database Key

The Database Key is an API key associated with an individual database created by an user (team member). This key is associated only with this database and it can be used to execute operations in it. You can retrieve these keys on your Databases' list section.

There are three types of database keys with different roles:

  • Master Key: allows you to do everything in your database, executing read, write operations and even modeling your columns and dimensions
  • Read Key: allows you to execute only read operations in your database (queries)
  • Write Key: allows you to execute only write operations in your database (insertions, updates and deletions)
  • Custom Key: allows you to do specific operations that can be configured to only be executed in allowed columns from a database, filtering the data that should be shown and restricting its access from defined IPs and domains.

Master Key

The master key allows you to make requests to insert records, query them and even model columns and dimensions.

The following endpoints can be accessed by these keys through the HTTP methods shown below:

Endpoint HTTP Methods Description
/database GET
  • Retrieve the settings for this database
/column POST
PUT
DEL
  • Create columns
  • Update columns
  • Delete columns
/insert POST
  • Insert data
/update POST
  • Update data
/delete POST
  • Delete data
/query/count/entity POST
  • Execute a count query
/query/count/event POST
  • Execute a count event query
/query/count/entity/total POST
  • Execute a count total query
/query/exists/entity POST
  • Execute an exists query
/query/aggregation POST
  • Execute an aggregation query
/data_extraction/result POST
  • Execute a data extraction result query
/data_extraction/score POST
  • Execute a data extraction score query
/sql POST
  • Execute a SQL query
/query/saved POST
GET
  • Create a saved query
  • Retrieve all registered saved queries
/query/saved/:query_name POST
PUT
DEL
GET
  • Execute the defined saved query
  • Update a registered saved query
  • Delete a registered saved query
  • Retrieve the saved query

Read Key

The Read key can be used for querying data from the database. However, it doesn't allow actions that would change the data stored.

The following endpoints can be accessed by this key through the HTTP methods shown below:

Endpoint HTTP Methods Description
/database GET
  • Retrieve the settings for this database
/column GET
  • List the columns for this database
/query/count/entity POST
  • Execute a count query
/query/count/event POST
  • Execute a count event query
/query/count/entity/total POST
  • Execute a count total query
/query/exists/entity POST
  • Execute an exists query
/query/aggregation POST
  • Execute an aggregation query
/data_extraction/result POST
  • Execute a data extraction result query
/data_extraction/score POST
  • Execute a data extraction score query
/sql POST
  • Execute a SQL query
/query/saved/:query_name GET
  • Retrieve the result for the saved query

Write Key

The Write key only allows creating columns and inserting data to the database. With this key, you cannot run queries.

The following endpoints can be accessed by this key through the HTTP methods shown below:

Endpoint HTTP Methods Description
/column POST
  • Create columns
/insert POST
  • Insert data
/update POST
  • Update data
/delete POST
  • Delete data

Custom Key

SlicingDice enables you to create custom database keys, which can be configured to allow inserting and querying only over specific columns from a database, defining filters and whitelists to use this key.

There are three types of custom database keys:

  • Read-Write: allows you to execute the same operations that a Master Key is able to do.
  • Read-Only: allows you to query data and update saved queries using only the allowed columns
  • Write-Only: allows you to execute POST requests on the /insert, /update and /delete endpoints

Notice that the filters and whitelist defined to the custom key are automatically applied to it while executing your operations