Skip to main content

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 focused on data enrichment (Ex. Heron Data) can integrate with Unit to get transaction data and provide customers better data for more delightful experiences.
  • Rewards partners (Ex. Kard, Patch, Bumped) can access shared customer data to deliver cashback and other perks more efficiently. 
  • Partners specializing in investments (Ex. Alpaca, 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.


Configuration#

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.

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.

Testing#

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

Get Partner Orgs#

Get the list of your partner orgs

VerbGET
Urlhttps://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.

VerbPOST
Urlhttps://api.s.unit.sh/partners/token
Timeout (Seconds)5

Attributes#

NameTypeDescription
orgIdstringID of org
scopesstringList of Scopes separated by spaces, please refer to the relevant endpoint to get the required scope
sourceIpstringOptional but recommended. A comma separated list of IP addresses that are allowed to use the on behalf token (no spaces allowed).
expiresInintegerOptional. 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        }    }}