HolyWally Partner API

This document describes features that HolyWally exposed for integrations.

Current version	Updated by	Updated at
Version 1.0.8	Tom Jakopovic	11 Sept 2023
Version 1.0.7	Tom Jakopovic	8 Feb 2023
Version 1.0.6	Tom Jakopovic	16 Nov 2022
Version 1.0.5	Tom Jakopovic	3 Nov 2022
Version 1.0.4	Tom Jakopovic	11 Oct 2022
Version 1.0.3	Ivan Bajalovic	31 Aug 2022
Version 1.0.2	Ivan Bajalovic	25 Aug 2022
Version 1.0.1	John Rutledge	15 Aug 2022
Version 1.0.0	Ivan Bajalovic	1 Aug 2022

Terminology

• User Details Provider - A provider which stores personal data
• Authentication Provider - A provider which is responsible for authenticating users

Prerequisites

Each request should contain the following three header values:

• X-Company-Id (value provided by HolyWally team)
• X-API-Key (an API key provided by HolyWally team)
• X-Signature (calculated request signature)
• X-Timestamp

Signing the request

String to be signed should be concatenated from the following values

• HTTP Verb + Resource URI (including query params, in lexicographical order)
• Timestamp (Current Unix timestamp in milliseconds)
• Host
• Body Request digest - SHA256 Hash

Example

StringToSign =
"POST /users" + 
"1659345343000" + 
"partner-api.holywally.com" + 
"{contentSha256Hash}"

Signature = Base64Encode(RSASign(RsaPrivateKey, StringToSign, 'SHA256'))

User Management

User Directory

User directory is a group of users within the HolyWally Platform. HolyWally creates a default user directory for each client, named “Default”. However, you can also create user directories to allow you to further segment your end-users into different groups.

For example, in business-to-business implementations, each of your business customers can be assigned their own user directory. Alternatively, your end-users can be grouped by departments, units, function etc. using user directories.

Each user can be assigned multiple user directories. However, HolyWally does not support nested user directories at this stage.

Get existing user directories

GET /user-directories

Response HTTP Status 200

[{
  "id": "e7df3ab2-bbd1-4262-ab07-f64e016924e6",
  "name": "Looney Tunes",
  "externalRefIds": ["org: 5g4VHaznbY"]
}]

info

The field externalRefIds is an array of alias identifiers of this entity in User Details Provider.

Create a user directory

Creates a user directory in the HolyWally platform. You may also include an external reference ID externalRefIds to associate the user directory with a record in your database at the point of creation. If userDirectoryDetails is provided, a record will be created in the User Details Provider's database with an externalRefIds set internally.

Example 1 Create user directory in HolyWally Platform, with an associated external reference ID (optional)

Body:

{
  "name": "Looney Tunes",
  "externalRefIds": ["org: 5g4VHaznbY"]
}

Response: HTTP Status 201

{
  "id": "e7df3ab2-bbd1-4262-ab07-f64e016924e6",
  "name": "Looney Tunes",
  "externalRefIds": ["org: 5g4VHaznbY"]
}

Example 2 Create user directory in HolyWally Platform and User Details Provider's database

POST /user-directories

Body:

{
  "name": "Looney Tunes",
  "userDirectoryDetails": {
      "corporate": "Looney Tunes",
      "by": "Warner Bros"
  }
}

Response: HTTP Status 201

{
  "id": "e7df3ab2-bbd1-4262-ab07-f64e016924e6",
  "name": "Looney Tunes",
  "externalRefIds": ["org: 5g4VHaznbY"]
}

If userDirectoryDetails field is provided, it will update any existing associated record in the User Details Provider.

PATCH /user-directories/{ext-user-directory-id}

Body:

{
  "name": "Looney Tunes by Warner Bros",
  "userDirectoryDetails": {
      "address": "2nd Street 503"
  }
}

Response: HTTP Status 200

{
  "id": "e7df3ab2-bbd1-4262-ab07-f64e016924e6",
  "name": "Looney Tunes by Warner Bros",
  "externalRefIds": ["org: 5g4VHaznbY"]
}

---

DELETE /user-directories/{ext-user-directory-id}

Response: HTTP Status 204

Add aliases to User Directories

Connect User Directory with additional external reference IDs.

POST /user-directories/{ext-user-directory-id}/alias

Body:

[{ "externalRefId": "another_ref_id" }]

Response: HTTP Status 201

{
  "id": "e7df3ab2-bbd1-4262-ab07-f64e016924e6",
  "name": "Looney Tunes",
  "externalRefIds": ["org: 5g4VHaznbY", "another_ref_id"]
}

---

DELETE /user-directories/{user-directory-id}/alias

Body:

[{ "externalRefId": "another_ref_id" }]

Response: HTTP Status 200

{
  "id": "e7df3ab2-bbd1-4262-ab07-f64e016924e6",
  "name": "Looney Tunes",
  "externalRefIds": ["org: 5g4VHaznbY"]
}

Users

A user refers to an individual using the HolyWally Platform. The user record represents all information related to the user such as name, address, date of birth, etc.

HolyWally offloads all user record, which can also contain sensitive information, to an external Authentication Provider (e.g. Auth0). Clients may opt to use their own Authentication Provider and assign an authentication provider identifier to that user. Furthermore, clients can also instead choose to store user record in a separate database which HolyWally refers to as User Details Provider.

As such, HolyWally supports a variety of Authentication Provider and User Details Providers and needs to be able to connect these to the user.

Hence, a user record should have 2 references assigned to it:

• Authentication provider identifiers
• User details provider identifiers

Onboarding a new user should consist of the following steps:

• Create user record
• Connect authentication account
  • HolyWally can either create an authentication account with the Authentication provider, or
  • assign Authentication Provider identifier (in case user already has an authentication account)
• Assign User Details Providers identifier
• Assign a wallet - Assign a wallet provider ID where providerType="Banking" for that wallet

Create a user account

Creates a user account in the HolyWally platform. User should be assigned to at least one user directory. If userDetails field is present, data provided will be stored in User Details Provider, and an externalRefId will be set in HolyWally platform.

POST /users

Body:

{
  "firstName": "Wile",
  "lastName": "Coyote",
  "userDirectoryIds": ["e7df3ab2-bbd1-4262-ab07-f64e016924e6"],
  "userDetails": {
      "address": {
          "line1": "2nd Street 401"
      }
  }
}

Response: HTTP Status 201

{
  "id": "2bfc9c24-083a-4769-b9c0-587dabecf02c",
  "firstName": "Wile",
  "lastName": "Coyote",
  "userDirectoryIds": ["e7df3ab2-bbd1-4262-ab07-f64e016924e6"],
  "externalRefIds": ["uid:tNHFm92lXk"]
}

Get user account

Get's details on user's account

GET /users/

Body:

{
  "firstName": "Wile",
  "lastName": "Coyote",
  "userDirectoryIds": ["e7df3ab2-bbd1-4262-ab07-f64e016924e6"],
  "userDetails": {
      "address": {
          "line1": "2nd Street 401"
      }
  }
}

Response: HTTP Status 201

{
  "id": "2bfc9c24-083a-4769-b9c0-587dabecf02c",
  "firstName": "Wile",
  "lastName": "Coyote",
  "userDirectoryIds": ["e7df3ab2-bbd1-4262-ab07-f64e016924e6"],
  "externalRefIds": ["uid:tNHFm92lXk"]
}

Connect user details provider

POST /users/{ext-user-id}/alias

Body:

[{ "externalRefId": "uid:8LQZi8AZbp" }]

Response: HTTP Status 201

{
  "id": "2bfc9c24-083a-4769-b9c0-587dabecf02c",
  "firstName": "Wile",
  "lastName": "Coyote",
  "userDirectoryIds": ["e7df3ab2-bbd1-4262-ab07-f64e016924e6"],
  "externalRefIds": ["uid:tNHFm92lXk", "uid:8LQZi8AZbp"]
}

---

DELETE /users/{ext-user-id}/alias

Body:

[{ "externalRefId": "uid:8LQZi8AZbp" }]

Response: HTTP Status 200

{
  "id": "2bfc9c24-083a-4769-b9c0-587dabecf02c",
  "firstName": "Wile",
  "lastName": "Coyote",
  "userDirectoryIds": ["e7df3ab2-bbd1-4262-ab07-f64e016924e6"],
  "externalRefIds": ["uid:tNHFm92lXk"]
}

Connect authentication provider

There are two endpoints available: one for creating an account with the authentication provider, and another for assigning existing authentication account to the user.

Create a new authentication account

POST /users/{ext-user-id}/auth-account

Body:

{
  "email": "wile@coyote.com",
  "phoneNumber": "+658888444",
  "authenticationType": "username-password-authentication"
}

info

Available options for the authenticationType field:

• username-password-authentication
  • for an email/password authentication
• email
  • for passwordless authentication, using email
• phone
  • for passwordless authentication, using phone number

Response: HTTP Status 201

{
  "id": "abf5053b-bd00-48e8-a026-cd0b8f3679f5",
  "authenticationType": "username-password-authentication"
}

---

POST /users/{ext-user-id}/assign-auth-account Body:

{
  "authIdentifier": "auth0|6306hfd44441b2491613a765",
  "authenticationType": "username-password-authentication"
}

info

Available options for authenticationType field:

• username-password-authentication
  • for an email/password authentication
• email
  • for passwordless authentication, using email
• phone
  • for passwordless authentication, using phone number

Response: HTTP Status 201

{
  "id": "abf5053b-bd00-48e8-a026-cd0b8f3679f5",
  "authenticationType": "username-password-authentication"
}

---

GET /users/{ext-user-id}/auth-account

Response: HTTP Status 200

{
  "id": "abf5053b-bd00-48e8-a026-cd0b8f3679f5",
  "authenticationType": "username-password-authentication"
}

---

DELETE /users/{ext-user-id}/auth-account

Body:

[{
  "authIdentifier": "auth0|6306hfd44441b2491613a765"
}]

Response: HTTP Status 204

User Controls

There are two levels of blocking access to the platform for a user, temporary (suspend user account) and final (close user account). Suspend action can be reverted by the Activate action. Closing user account is an irreversible action.

POST /users/{ext-user-id}/suspend

Response: HTTP Status 200

{
  "status": "success"
}

---

POST /users/{ext-user-id}/activate

Response: HTTP Status 200

{
  "status": "success"
}

---

POST /users/{ext-user-id}/close

Response: HTTP Status 200

{
  "status": "success"
}

Permissions and Policies

User access is controlled by permissions and policies. A permission is defined by a resource and an action, and an effect which can be allow or deny. Wildcard (*) for resource and action fields are available. A set of permissions is a Policy. Policy can be then attached to a user.

GET /policies

Response: HTTP Status 200

[{
    "id": "b07cc085-7483-43b1-96ad-6e24141f1492",
    "name": "Mobile App User"
},
{
    "id": "731b2993-30d3-4975-aa69-1b317d8e2737",
    "name": "Admin"
}]

---

Assign one or multiple policies to a user POST /users/{ext-user-id}/policies

Body:

[{ 
    policyId: "b07cc085-7483-43b1-96ad-6e24141f1492"
}]

Response: HTTP Status 201

{
    "status": "success"
}

---

Gets all policies assigned to user

GET /users/{ext-user-id}/policies

Response: HTTP Status 200

[
    {
        "name": "Corporate Super Admin",
        "id": "519b9e5f-d9a3-481a-a71e-535d586235ce"
    }
]

---

Remove a specific policy from a user

DELETE /users/{ext-user-id}/policies/{policy-id}

Response: HTTP Status 204

Wallet Management

Wallets

Get available wallets.

GET /wallets

Response: HTTP Status 200

[
  {
    "name": "My Personal",
    "type": "personal",
    "id": "183bf963-6a3e-4738-ac1d-d40319b42c41"
  },
  {
    "name": "Work Wallet",
    "type": "corporate",
    "id": "b5278a9c-1cff-452f-a74d-4f9bb4a68c3c"
  },
  {
    "name": "Master Corporate",
    "type": "master",
    "id": "cf4cff5f-37c4-4ac6-9a30-4b872240ea83"
  },
]

Account Presets

Get Available account presets

Get available account presets that are pre-configured on HolyWally platform.

GET /account-presets

Response: HTTP Status 200

[
  {
    "id": "a11bbd16-f5c4-4aa2-92d2-03efe8d7a8e1",
    "name": "Corporate User",
    "cardPresets": [{
        "cardPresetId": "4da463d8-7977-45b1-b838-db309c8dd33a",
        "name": "Virtual card"
    }],
    "description": "This preset will assign a corporate wallet to a user and issue him a card"
  },
  {
    "id": "c49dd800-5116-4d57-8e26-d32aa5d72069"
    "name": "Personal",
    "cardPresets": [{
        "cardPresetId": "7eb7a53a-6b8e-4d28-9648-956403b8bd7a",
        "name": "Virtual card"
    }],
    "description": "Create personal account"
  },
  {
    "id": "4dd8d33d-e5ef-494e-b91a-99cac97aa6a8"
    "name": "Master",
    "cardPresets": [],
    "description": "Master account"
  }
]

---

Create an account for a user, from an account preset

Account will be created with corresponding BaaS platform. If the account preset has connected Card Presets, for each card preset a card will be issued to user too.

POST /users/{ext-user-id}/account-presets/{account-preset-id}

Response: HTTP Status 201

Get Wallet Providers

Get available wallet providers for a given App.

GET /wallets/{wallet-id}/wallet-providers

Response: HTTP Status 200

[
  {
    "id": "a11bbd16-f5c4-4aa2-92d2-03efe8d7a8e1",
    "walletId": "183bf963-6a3e-4738-ac1d-d40319b42c41",
    "providerId": "9ce640f3-c204-4ea7-98e9-b0f4678922cf",
    "providerName": "Onfido",
    "providerType": "Kyc",
  },
  {
    "id": "f3ae7db2-001c-9a54-bf07-e66e24e60169",
    "walletId": "b5278a9c-1cff-452f-a74d-4f9bb4a68c3c",
    "providerName": "Episode Six",
    "providerType": "Banking",
    "providerId": "ba07802a-ec7f-4bbd-bf11-b0706ae673bc"
  },
]

Assign Wallets to a User

Assign one or many wallets(via the wallet provider) to a User. The clientId field should point to a end user account within BaaS platform.

POST /users/{ext-user-id}/wallets

Body:

[{
  "walletProviderId" : "f3ae7db2-001c-9a54-bf07-e66e24e60169",
  "clientId": "1004X10000560400895"
}]

Response: HTTP Status 201

{
    "status": "success"
}

Get Wallets assigned to a User

Get's all wallets assigned to user

GET /users/{ext-user-id}/wallets

Response: HTTP Status 200

[
    {
        "name": "Corporate",
        "type": "Corporate",
        "id": "ed9a7f18-38d5-463a-a726-6658ef0461d3"
    }
]

Remove user from a wallet

DELETE /users/{ext-user-id}/wallets

Body:

[{
  "walletProviderId" : "f3ae7db2-001c-9a54-bf07-e66e24e60169"
}]

Response: HTTP Status 204