Users

There are two types of users defined in the IF Platform.
1. Human: Represents individuals having email and password as login credentials to access the back-office or front-office application of the IF Platform.
2. Machine: Represents machines having a private key to generate JWT tokens as authentication information to access the API of the IF Platform.

There are two categories of users defined in the IF Platform.
1. Internal: Users that can access the back-office application or platform API. Human users in this category are usually employees of your company.
2. External: User that can access the front-office application. Human users in this category are usually users belonging to clients or clients themselves. With the newest features, external human users can be used for different functionalities such as Cardholders.

The current endpoints, defined below, can be used to access or manipulate data of external human users. Internal users and machine users are not available via these endpoints.

Creating A User

POST /users

There are 2 ways to create an external human user on the IF Platform.

1. External Human Invitation: Invitation via Email

Users can be invited to corporate clients. Invitation doesn't actually create a user record, it sends an invitation email to user. Once user navigates using the link in the email and signs up to the system, then user record is created. That's why response of this workflow doesn't include an ID for user model.

List of values that userClientRelation can be set as:

director
shareholder
director-and-shareholder
authorized-person

{
  "workflow": {
    "code": "human.external.invitation"
  },
  "data": {
    "user": {
      "email": "[email protected]",
      "identity": {
        "type": "individual",
        "givenName": "Bariscan",
        "familyName": "Akin"
      }
    },
    "invitations": [
      {
        "clientId": "00000000-0000-0000-0000-000000000000",
        "userClientRelation": "director"
      },
      {
        "clientId": "00000000-0000-0000-0000-000000000000",
        "userClientRelation": "authorized-person"
      }
    ]
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "human.external.invitation"
  },
  "data": {
    "user": {
      "email": "[email protected]",
      "identity": {
        "type": "individual",
        "givenName": "Bariscan",
        "familyName": "Akin"
      },
      "category": "external",
      "type": "human"
    },
    "invitations": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "clientId": "00000000-0000-0000-0000-000000000000",
        "userClientRelation": "director",
        "status": "pending"
      },
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "clientId": "00000000-0000-0000-0000-000000000000",
        "userClientRelation": "authorized-person",
        "status": "pending"
      }
    ]
  },
  "connect": {},
  "metadata": {}
}

Possible values of user invitation status:

pending (initial status)
accepted
rejected
cancelled

2. Direct Creation of External Human Users

This workflow is used to create a user using the details in the payload. User record is created directly, response contains ID of the user. These users cannot access the front office offered by IF. To be able to give access to front office, users must be invited using human.external.invitation workflow.

email, givenName and familyName are required. birthDate, phone and residentialAddress are optional.

userClientRelations is an optional feature add connects the user to a client directly on user creation.

{
  "workflow": {
    "code": "human.external.direct"
  },
  "data": {
    "user": {
      "email": "[email protected]",
      "identity": {
        "type": "individual",
        "givenName": "bruce",
        "familyName": "wayne",
        "birthDate": "1987-01-01"
      },
      "profile": {
        "phone": "+441234567890",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        }
      }
    },
    "userClientRelations": [
      {
        "clientId": "00000000-0000-0000-0000-000000000000"
      }
    ]
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "human.external.direct"
  },
  "data": {
    "user": {
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "[email protected]",
      "identity": {
        "type": "individual",
        "givenName": "bruce",
        "familyName": "wayne",
        "birthDate": "1987-01-01"
      },
      "profile": {
        "phone": "+441234567890",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        }
      },
      "category": "external",
      "type": "human",
      "status": "active"
    },
    "userClientRelations": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "userId": "00000000-0000-0000-0000-000000000000",
        "clientId": "00000000-0000-0000-0000-000000000000",
        "status": "allowed"
      }
    ]
  },
  "connect": {},
  "metadata": {}
}

Possible values of user status:

active (initial status)
inactive

Updating A User

PATCH /users/{userId}

email, identity, profile and status are updateable fields. This endpoint only updates the fields presented in the payload; values of other fields won't be updated.

{
  "workflow": {
    "code": "human.external.direct"
  },
  "data": {
    "user": {
      "email": "[email protected]",
      "identity": {
        "type": "individual",
        "givenName": "bruce",
        "familyName": "wayne",
        "birthDate": "1987-01-01"
      },
      "profile": {
        "phone": "+441234567890",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        }
      },
      "status": "active"
    }
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "human.external.direct"
  },
  "data": {
    "user": {
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "[email protected]",
      "identity": {
        "type": "individual",
        "givenName": "bruce",
        "familyName": "wayne",
        "birthDate": "1987-01-01"
      },
      "profile": {
        "phone": "+441234567890",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        }
      },
      "category": "external",
      "type": "human",
      "status": "active"
    }
  },
  "connect": {},
  "metadata": {}
}

Accessing User Data

Invited users won't be available via these APIs until they have accepted their invitation. This is because user resources are created after an invitation is accepted. You can check the statuses of existing invitations using the APIs defined in the following section.

List Users

GET /users

Supported query parameters:

parameter	description	requirement
metadata.page.number	0-indexed, default=0	optional
metadata.page.size	default=10	optional
data.user.category	category of user. must be external	required
data.user.email	email of the user	optional

{
  "workflow": {},
  "data": {
    "users": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "email": "[email protected]",
        "identity": {
          "type": "individual",
          "givenName": "Elif",
          "familyName": "Matraç",
          "birthDate": "1987-01-01"
        },
        "profile": {
          "phone": "+441234567890",
          "residentialAddress": {
            "country": "GB",
            "region": "England",
            "city": "London",
            "street": "Baker Street",
            "houseNumber": "221B",
            "postalCode": "XYZ ABC",
            "refinement": ""
          }
        },
        "category": "external",
        "type": "human",
        "status": "active"
      },
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "email": "[email protected]",
        "identity": {
          "givenName": "John",
          "familyName": "Doe",
          "birthDate": "1987-01-01"
        },
        "profile": {
          "phone": "+441234567890",
          "residentialAddress": {
            "country": "GB",
            "region": "England",
            "city": "London",
            "street": "Baker Street",
            "houseNumber": "221B",
            "postalCode": "XYZ ABC",
            "refinement": ""
          }
        },
        "category": "external",
        "type": "human",
        "status": "active"
      }
    ]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 10,
      "number": 0,
      "totalElements": 2,
      "totalPages": 1
    }
  }
}

Get a User

GET /users/{userId}

{
  "workflow": {},
  "data": {
    "user": {
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "[email protected]",
      "identity": {
        "type": "individual",
        "givenName": "Elif",
        "familyName": "Matraç",
        "birthDate": "1987-01-01"
      },
      "profile": {
        "phone": "+441234567890",
        "residentialAddress": {
          "country": "GB",
          "region": "England",
          "city": "London",
          "street": "Baker Street",
          "houseNumber": "221B",
          "postalCode": "XYZ ABC",
          "refinement": ""
        }
      },
      "category": "external",
      "type": "human",
      "status": "active"
    }
  },
  "connect": {},
  "metadata": {}
}

Accessing User Invitations

User invitations can be queried using the email of the invited user.

List User Invitations

GET /users/{userEmail}/invitations

{
  "workflow": {},
  "data": {
    "userInvitations": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "clientId": "00000000-0000-0000-0000-000000000000",
        "userClientRelation": "authorized-person",
        "status": "pending"
      }
    ]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 10,
      "number": 0,
      "totalElements": 1,
      "totalPages": 1
    }
  }
}

Get a User Invitation

GET /users/{userEmail}/invitations/{usersInvitationId}

{
  "workflow": {},
  "data": {
    "userInvitation": {
      "id": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "userClientRelation": "authorized-person",
      "status": "pending"
    }
  },
  "connect": {},
  "metadata": {}
}

Accessing User Client Relations

Users must be permitted to access client data and get a card using a client's accounts. This relation is created automatically after an invitation is accepted by the user. However, this relation must be created using create API here when direct workflow is used to create a user.

Create User Client Relations

Users must be permitted to clients to access their data and be used as a cardholder on client's accounts.

Possible values of user client relation status:

allowed (initial status)
revoked

POST /users/{userId}/client-relations

{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "userClientRelations": [
      {
        "clientId": "00000000-0000-0000-0000-000000000000"
      }
    ]
  },
  "connect": {},
  "metadata": {}
}

{
  "workflow": {
    "code": "direct"
  },
  "data": {
    "userClientRelations": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "userId": "00000000-0000-0000-0000-000000000000",
        "clientId": "00000000-0000-0000-0000-000000000000",
        "status": "allowed"
      }
    ]
  },
  "connect": {},
  "metadata": {}
}

List User Client Relations

GET /users/{userId}/client-relations

Supported query parameters:

parameter	description	requirement
metadata.page.number	0-indexed, default=0	optional
metadata.page.size	default=10	optional
data.userClientRelation.clientId	ID of client	required
data.userClientRelation.status	status of user client relation	optional

{
  "workflow": {},
  "data": {
    "userClientRelations": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "userId": "00000000-0000-0000-0000-000000000000",
        "clientId": "00000000-0000-0000-0000-000000000000",
        "status": "allowed"
      }
    ]
  },
  "connect": {},
  "metadata": {
    "page": {
      "size": 10,
      "number": 0,
      "totalElements": 1,
      "totalPages": 1
    }
  }
}

Get a User Client Relation

GET /users/{userId}/client-relations/{id}

{
  "workflow": {},
  "data": {
    "userClientRelation": {
      "id": "00000000-0000-0000-0000-000000000000",
      "userId": "00000000-0000-0000-0000-000000000000",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "status": "allowed"
    }
  },
  "connect": {},
  "metadata": {}
}