Connections Reference

Certain data providers might require 3-legged authentication/authorization to access the data they provide. Even if you're unfamiliar with this specifics of this process, you've probably seen it in action if you've ever signed into a service with Google or with Facebook, etc. Essentially 3-legged authentication/authorization stipulates an interaction between three parties (the 3 "legs" of the workflow) that gives an end-user an opportunity to grant or deny data access to your application. BitScoop Connections are manifestations of these "links" that your customers make to data providers by way of your Maps and help you deal with these workflows more easily.

For a typical use-case, consider the Google APIs. As a developer, you're able to leverage Google APIs provided you've obtained an API key (often times by way of creating an "app"). However, obtaining an API key does not implicitly grant your application access to everyone's email on Google. So let's say that that your application needs access to an email inbox for a particular user. How would we go about querying this information, or, more importantly, how can we ensure that we have permission to do so? For this we need to rely on explicit permission grants from the other two "legs" of the workflow; in this case Google and the owner of the email inbox.

So, in theory we've already obtained a root Google API key. This proves to Google that we're at least an authorized developer of their system even if we don't have access to anybody's data just yet. We then need to obtain an access token using that API key and, sometimes, specify which scopes (or permissions) we'd like that access token to have. Once we request that token, what we more or less get back from Google is a URL that we should direct one of our end-users to so that they may be given the opportunity to grant us the permissions we need to drive our application. Our users presumably visit the URL we give them, either grant or deny the permissions we need, and then get redirected to a "redirect URL" we've specified in our application.

We then use this access token along with our root API key to actually request data from the system. In this way:

  • All three "legs" have granted permission to view the data.
  • Our end-users can revoke our application's permissions any time they see fit without sending us a support request.
  • We can use the same API routes to obtain different users' data. We essentially indicate the user by specifying a different obtained access token.

While the various data providers' 3-legged auth processes are typically secure and technically sound, there are a few shortcomings.

  • Different services have different implementations for auth workflows often with eccentricities and idiosyncrasies.
  • Redirect URLs are typically specified on the app we've registered with an API or service, so they can't vary based on end-user.
  • Multiple access tokens pertaining to the same user are possible but are also unique so it's difficult to relate our end-users 1:1 with access tokens.

BitScoop keeps track of the Connection information, such as the status and access tokens, to remedy these shortcomings and vastly simply your application's auth process.

Keep in mind that you always have access to the complete set of information attached to a Connection. So it's easy to upload any existing "connections" you might have, or to export BitScoop Connections elsewhere in your application.

Collection Route GET

https://api.bitscoop.com/connections

The collection route for Connections offers methods to interact with every one of your Connections. If you're interested in creating new Connections, you'll need to create a Map first and then you'll use the Map-specific Connection route.

GET List all owned Connections

Returns an array of your Connections. The connection object structure contains a few fields that characterize its state and the information associated with it.

Name Type Description
id string A UUID4 unique identifier for the Connection object.
name string The name of the Connection. Not used except for your own organizational purposes.
auth.status.complete boolean A flag indicating whether the third party associated with the Connection has granted the requested scopes.
auth.status.authorized boolean A flag indicating whether the third party associated with the Connection has approved a scope change.
auth.data.access_token string The access token used to sign requests to the external data provider. This token may not be present for all authentication types.
metadata object A free-form object containing the meta data obtained for the Connection using the meta endpoint. This field will not exist if no meta endpoint is configured.
created string The date at which the Connection was created.
updated string The date at which the Connection was last updated.
provider_id string A UUID4 unique identifier of the Map associated with the connection.

Example Response:

HTTP/1.1 200 OK

[
    {
        "id": "f1fe5cb8cb1043948c90be86d72c8985",
        "name": "My Connection",
        "auth": {
            "status": {
                "complete": true ,
                "authorized": true ,
            },
            "data": {
                "access_token": "12345" ,
            }
        },
        "metadata": {
            "id": "123456"
            "email": "john.doe@example.com"
        },
        "created": "2017-05-10T20:24:57.762Z",
        "updated": "2017-05-10T20:24:57.762Z",
        "provider_id": "09dcac0883a04e45910a32e716ac8ee4"
    },

    ...
]

Instance Route GET PATCH DELETE

https://api.bitscoop.com/connections/[connection_id]

The instance route for Connections offers a methods to interact with Connections on an individual basis.

Path parameters

Name Description
connection_id The UUID4 ID for the individual connection.

GET Obtain details about a single Connection

Returns a single Connection matching the specified connection_id. The connection object structure contains a few fields that characterize its state and the information associated with it.

Name Type Description
id string A UUID4 unique identifier for the Connection object.
name string The name of the Connection. Not used except for your own organizational purposes.
auth.status.complete boolean A flag indicating whether the third party associated with the Connection has granted the requested scopes.
auth.status.authorized boolean A flag indicating whether the third party associated with the Connection has approved a scope change.
auth.data.access_token string The access token used to sign requests to the external data provider. This token may not be present for all authentication types.
metadata object A free-form object containing the meta data obtained for the Connection using the meta endpoint. This field will not exist if no meta endpoint is configured.
created string The date at which the Connection was created.
updated string The date at which the Connection was last updated.
provider_id string A UUID4 unique identifier of the Map associated with the connection.

Example Response:

HTTP/1.1 200 OK

{
    "id": "f1fe5cb8cb1043948c90be86d72c8985",
    "name": "My Connection",
    "auth": {
        "status": {
            "complete": true ,
            "authorized": true ,
        },
        "data": {
            "access_token": "12345" ,
        }
    },
    "metadata": {
        "id": "123456"
        "email": "john.doe@example.com"
    },
    "created": "2017-05-10T20:24:57.762Z",
    "updated": "2017-05-10T20:24:57.762Z",
    "provider_id": "09dcac0883a04e45910a32e716ac8ee4"
}

PATCH Update a single Connection

Updates a single Connection matching the specified connection_id. Returns the updated Connection.

Body:

Name Type Description
name string optional The name of the Connection. Not used except for your own organizational purposes.
auth.status.complete boolean optional A flag indicating whether the third party associated with the Connection has granted the requested scopes.
auth.status.authorized boolean optional A flag indicating whether the third party associated with the Connection has approved a scope change.
auth.data.access_token string optional The access token used to sign requests to the external data provider. This token may not be present for all authentication types.

Example Response:

HTTP/1.1 200 OK

{
    "id": "f1fe5cb8cb1043948c90be86d72c8985",
    "name": "My Connection",
    "auth": {
        "status": {
            "complete": true ,
            "authorized": true ,
        },
        "data": {
            "access_token": "12345" ,
        }
    },
    "metadata": {
        "id": "123456"
        "email": "john.doe@example.com"
    },
    "created": "2017-05-10T20:24:57.762Z",
    "updated": "2017-05-10T20:24:57.762Z",
    "provider_id": "09dcac0883a04e45910a32e716ac8ee4"
}

DELETE Delete a single Connection

Deletes a single Connection matching the specified connection_id.

Example Response:

HTTP/1.1 204 No Content

Complete Route GET

https://auth.api.bitscoop.com/done/[map_id]

The complete route serves as an automatically provisioned redirect location for your apps that require 3-legged auth negotiation. The endpoint should not be directly called, but it is instead visited by your end-users during the auth negotiation process.

The only actions you need to take are setting up the auth configuration on your Maps where appropriate and setting the value of the "redirect URL" (or similar) on the corresponding app you've created with a data provider. In this way as your end-users grant or deny permissions to your app they will be redirected by the data provider to this URL. Once they reach this URL, the Connection you have provisioned for them will be completed and they will be redirected once again to the final location (which you configure).

Name Description
map_id The ID of the Map with which the incomplete Connection is associated.

There are several parameters that are required as part of various 3-legged auth processes. However these parameters are applied automatically by the services with which you're negotiating access.

GET Completes a Connection finishing the 3-legged auth process

Example Response:

HTTP/1.1 302 Moved Temporarily

Location: [redirect_url]

When creating a Connection you have an opportunity to specify the redirect_url that manifests as the final redirect location. If you choose to forgo this option the redirect_url will instead be derived from the associated Map's auth configuration block.

A few query parameters will be specified automatically on top of the base redirect_url that you configure. For example, let's say you've configured your Map with a redirect URL of https://www.example.com. The actual URL that your end-user will be directed to will be:

https://www.example.com?connection_id=[connection_id]

Where the connection_id depends on which Connection has been completed.

If you have stipulated Connection uniqueness by way of metadata you will have an additional query parameter.

https://www.example.com?connection_id=[connection_id]&existing_connection_id=[existing_connection_id]

In this case the Connection with the ID connection_id will be automatically deleted and you should instead use the existing_connection_id to obtain the active Connection.

A potential use case for Connection uniqueness is user sign-up and sign-in. In this case we're interested in associating a remote account (e.g. Google, Facebook, etc.) 1:1 with a Connection. If we didn't have Connection uniqueness, it would be possible for a user to sign-up for multiple accounts with the same Google account. While this isn't a security risk per se it does make it impossible to uniquely determine which account a user intends to sign in to.