Authorized Users

Overview

Authorized Users represent individuals that have full access to the Customer's financials - they are able to authenticate and create a Customer Token and initiate any activity on behalf of the customer. This feature is used mostly in Business customers and Sole Proprietors, where the customer is a Business that can have multiple individuals managing its financials. Additionally, Authorized Users have access to all customer accounts through exchange networks, such as Plaid, enabling seamless financial data integration.

note

For Individual customers, Authorized users should not be used, except for very specific use cases. Please consult Unit if you plan to use this feature for individuals.

Add Authorized Users

Add authorized users for a customer. The Customer Update webhook event will be fired.

note

When adding an authorized user with the same Email as an existing authorized users of the customer, the existing authorized user info will be updated according to the info in the request.

Verb	POST
Url	https://api.s.unit.sh/customers/:customerId/authorized-users
Required Scope	customers-write
Data Type	addAuthorizedUsers
Timeout (Seconds)	5

Attributes

Name	Type	Description
authorizedUsers	Array of AuthorizedUser	Array of authorized users. The provided array items will be added to the existing ones.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	BusinessCustomer or IndividualCustomer	Customer resource. be either business or individual, as indicated by the type field.

Add Customer Authorized Users:

curl -X POST 'https://api.s.unit.sh/customers/10000/authorized-users'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "addAuthorizedUsers",
    "attributes": {
      "authorizedUsers": [
        {
          "fullName": {
            "first": "Erlich",
            "last": "Backman"
          },
          "email": "erlich@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "1234567890"
          }
        }
      ]
    }
  }
}'

Get by Id

Get an authorized user resource by id.

Verb	GET
Url	https://api.s.unit.sh/customers/{customerId}/authorized-users/{authorizedUserId}
Timeout (Seconds)	5

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	AuthorizedUser	Authorized user resource.

curl -X GET 'https://api.s.unit.sh/customers/8/authorized-users/20' \
-H "Authorization: Bearer ${TOKEN}"

List

List of authorized user resources. Filtering can be applied.

Verb	GET
Url	https://api.s.unit.sh/customers/{customerId}/authorized-users
Required Scope	customers
Timeout (Seconds)	5

Query Parameters

Name	Type	Default	Description
filter[jwtSubject]	string	(empty)	Optional. Filter authorized users by JWT subject.
filter[phone]	Phone	(empty)	Optional. Filter authorized users by phone.

curl -X GET 'https://api.s.unit.sh/customers/8/authorized-users?filter[ids][0]=20&filter[phone]={"countryCode": "1","number": "1234567890"}' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of AuthorizedUsers	Array of authorized user resources.

Example Response:

{
  "data": [
    {
      "type": "authorizedUser",
      "id": "42",
      "attributes": {
        "fullName": {
          "first": "Richard",
          "last": "Hendricks"
        },
        "email": "richard@piedpiper.com",
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        },
        "createdAt": "2020-05-13T09:07:47.645Z",
        "status": "Enabled",
        "evaluationStatus": "Evaluated",
        "evaluationId": "10020",
        "alertId": "159753159753"
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "banks": {
          "data": {
            "type": "banks",
            "id": [
              "1"
            ]
          }
        }
      }
    },
    {
      "type": "authorizedUser",
      "id": "88",
      "attributes": {
        "fullName": {
          "first": "Jone",
          "last": "Doe"
        },
        "email": "jone.doe@unit-finance.com",
        "phone": {
          "countryCode": "1",
          "number": "2025550108"
        },
        "createdAt": "2020-05-13T09:07:47.645Z",
        "jwtSubject": "3438c4c8-5061-70ba-5b5d-71418d796f60",
        "status": "Disabled",
        "evaluationStatus": "Evaluated",
        "evaluationId": "10028",
        "alertId": "159753159456"
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10001"
          }
        },
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        }
      }
    }
  ]
}

Remove Authorized Users

Remove existing authorized users from a customer. The Customer Update webhook event will be fired.

note

Authorized users emails are unique, when removing an authorized user it is identified only by its email address

Verb	DELETE
Url	https://api.s.unit.sh/customers/:customerId/authorized-users
Required Scope	customers-write
Data Type	removeAuthorizedUsers
Timeout (Seconds)	5

Attributes

Name	Type	Description
authorizedUsersEmails	Array of emails (strings)	The list of authorized users emails to remove from the customer.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	BusinessCustomer or IndividualCustomer	Customer resource. be either business or individual, as indicated by the type field.

Remove Customer Authorized Users:

curl -X DELETE 'https://api.s.unit.sh/customer/10000/authorized-users'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "removeAuthorizedUsers",
    "attributes": {
      "authorizedUsersEmails": [
        "jared@piedpiper.com"
      ]
    }
  }
}'