Authenticating Requests

BitScoop uses a form of Bearer Token auth to authenticate/authorize requests.

The only thing you need to do to access BitScoop resources is provision at least one API Key using the developer portal page bitscoop.com/keys. Every request to the API Toolbox must be signed with an authorization header containing a valid API Key token:

Authorization: Bearer {{ api_key_token }}

Creating a new API Key

API Keys cannot be created through the API itself, but rather through the developer portal page bitscoop.com/keys manually. You can generate as many API keys as you want, so feel free to leverage any number of API keys to silo access in your various applications.

At this time, BitScoop is not intended to be directly called by your end-users but rather is used for server-to-server communication (your applications talking to services on behalf of your end-users). As such, creating an API key for every one of your users, while possible, is not recommended. BitScoop offers a more appropriate solution to this design requirement by way of Connections.

When creating a key you can optionally supply a name so you can better keep track of access on your account. This name can be changed at any time and doesn't affect anything internally.

After the API Key is created, the authorization token will be visible which can be used to sign your requests.

You cannot regenerate the API Key token, nor can you choose your own token. However you can delete API Keys and create new API Keys whenever you'd like.

Controlling scope

You can easily limit which scopes an API Key has access to. In this way you can specify whether a key has, for instance, only access to reading your resources or fetching data from the Data API.

The scopes we currently support are:

Name Description
data Access to the BitScoop Data API.
maps:read Read permission for API Maps.
maps:write Write permission for API Maps
connections:read Read permission for Connections.
connections:read_auth Read permission for authentication information on Connections (e.g. auth tokens, keys, etc.)
connections:write Write permission for Connections (including creation).

At this time we do not support Map-specific permissions on API Keys. That is to say if a particular API Key has the connections:read permission it can read all of your Connections, not those just for one specific Map.

CIDR access limitations

You can limit which networks can access your BitScoop resources using any given API Key by specifying any number of CIDR block restrictions.

Each CIDR block functions as a whitelist permission, so if you haven't specified any CIDR blocks an API Key will be effectively disabled.

When an API Key is first created it will have a pre-filled CIDR block whitelist item of:

0.0.0.0/0

This means that any origin IP can use the API Key to access your resources (provided the API Key also has appropriate scopes).

You may be interested in developing a more robust or restrictive whitelist to improve the security of your BitScoop resources.

Disabling API Keys

If you'd like to temporarily suspend an API Key you can freely disable and re-enable it. Requests to the BitScoop platform signed with a disabled API Key token will be rejected.

Deleting API Keys

You can permanently disable BitScoop API Toolbox access on an API Key by deleting it. Once an API Key is deleted you will no longer be able to use the same token. For security reasons, BitScoop will not restore erroneously deleted API Keys.

API Key environments

Every API Key can have any number of environment variables stored on it in a flat JSON format. These environment variables are available for dynamic evaluation when using BitScoop to make outbound calls. The values of API Key environment variables can be of type boolean, string, and number.

Consider a minimal API Map example:

{
  "version": "1.0",
  "url": "https://api.example.com",
  
  "headers": {
    "Authorization": "Bearer 1234567890"
  },
  
  "endpoints": {
    "Stuff": {
      "route": "/stuff"
    }
  }
}

This Map is configured with one callable endpoint and will apply the HTTP header indicated on every outbound request. However, there is a potential problem problem with this solution: we've exposed our API key for example.com's services directly in our Map. If we're collaborating with multiple developers this may not be ideal. Furthermore we might have test and production configurations that demand the use of a different API key.

In any of these cases we can slightly modify the API Map as follows:

{
  "version": "1.0",
  "url": "https://api.example.com",
  
  "headers": {
    "Authorization": "Bearer {{ environment.api_key }}"
  },
  
  "endpoints": {
    "Stuff": {
      "route": "/stuff"
    }
  }
}

Now we have an abstracted placeholder for our outbound API key that references a context variable environment. This variable is the environment stored on the BitScoop API Key that we've used to make the request.

So if we have the environment:

{
  "api_key": "1234567890"
}

On our BitScoop API Key, then there is no functional difference between the two examples in the outbound requests, but we've successfully remedied the potential problems we've outlined.

There is more information about dynamic evaluation and how else it can be used within BitScoop on the Maps and Connections pages.