Partner API Tokens

Overview

Unit enables its clients to securely and reliably grant partners direct access to the user-permissioned data that Unit stores on shared customers. For example, if a partner needs access to the debit card details of a shared customer, they can fetch it directly instead of having to request the data from the client.

This helps partners more easily integrate into Unit's growing ecosystem and deliver seamless experiences for shared customers. As a result, companies building on Unit will gain access to a wider selection of solutions that can be integrated faster. This feature is available across all of Unit’s bank partners.

Partner API Tokens enable new functionalities like the following: 

• Partners providing small business accounting and expense tracking (e.g. Hurdlr) can integrate with Unit to easily get the required transaction data.
• Rewards partners (e.g. Kard or Patch) can access shared customer data to deliver cashback and other perks more efficiently. 
• Partners specializing in investments (e.g. Alpaca or Apex) can streamline transaction-based investing.

NOTE: Partner tokens currently only support read actions and do not allow the partner to subscribe to webhook events or take any action on behalf of the client.

Unit Customers: Requesting a Partner Token Set Up

Partner tokens make it easier for you to work with additional parters and provide a broader range of features to your customers - you don't have to invest in the engineering work to pass through information that Unit could share directly instead.

In order to get started, contact your Customer Success Manager to let us know that you'd like to work with a partner and to authorize them to access the required data. It's also helpful if you include a summary of the use case.

Unit Partners: Implementing Partner Tokens

Initial Set Up

Contact Unit to receive a partner user. This partner user will have access to the Partner Portal in the Unit Dashboard, where partner tokens are created.

We also recommend creating your own test client organization in Sandbox in order to test the entire flow independently as a partner. Once your test client is created, please contact Unit to allow your partner token to get data from your test client.

Technical Background

• A partner user can create partner tokens and other partner users
• The partner token is used to create on-behalf tokens
• Each on-behalf token gives access to one shared client’s data
• Each on-behalf token has specified scopes to control its access and specified endpoint(s) it can access
• The maximum expiration of each on-behalf token is 24 hours

Technical Flow

1. Log in with your partner user credentials to the Unit Dashboard. Go to Developer > API Tokens to create a Partner Token.
2. Fetch the orgId of the shared client with the Get Partner Orgs endpoint. Use your Partner Token for authorization.
3. Use the Create on Behalf Token endpoint to receive an on-behalf token for a shared client, using the orgId of the given client and your Partner Token for authorization.
4. Use the on-behalf token as authorization in order to fetch client data using the Unit API.

Get Partner Orgs

Get the list of your partner orgs

Verb	GET
Url	https://api.s.unit.sh/partners/orgs
Timeout (Seconds)	5

curl -X GET
 '{{server_url}}/partners/orgs' \
--header 'Authorization: Bearer $PartnerToken'

Response

Response is a JSON:API document.

200 OK

{
    "data": [
        {
            "type": "org",
            "attributes": {
                "orgId": "ipF58vfdszo=",
                "orgName": "Shared Client 1"
            }
        },
        {
            "type": "org",
            "attributes": {
                "orgId": "h5D8B5gyHtk=",
                "orgName": "Shared Client 2"
            }
        }
    ]
}

Create on-Behalf Token

Create an on-behalf token for a shared client.

Verb	POST
Url	https://api.s.unit.sh/partners/token
Timeout (Seconds)	5

Attributes

Name	Type	Description
orgId	string	ID of org
scopes	string	List of Scopes separated by spaces, please refer to the relevant endpoint to get the required scope
sourceIp	string	Optional but recommended. A comma separated list of IP addresses that are allowed to use the on behalf token (no spaces allowed).
expiresIn	integer	Optional. The lifetime of the token (in seconds). Maximum value is 86400 (24 hours). Default value is also 24 hours.

curl -X POST
'{{server_url}}/partners/token' \
--header 'Authorization: Bearer $PartnerToken' \
--header 'Content-Type: application/vnd.api+json' \
--data-raw '{
    "data": {
        "type": "createOnBehalfToken",
        "attributes": {
            "orgId": "h5D8B5gyHtk=",
            "scopes": "customers cards"
        }
    }
} '

Response

Response is a JSON:API document.

201 Created

{
    "data": {
        "type": "onBehalfToken",
        "attributes": {
            "token": <ON_BEHALF_TOKEN>,
            "expiresIn": 86400
        }
    }
}