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. Currently, internal human users can only be created on request.
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": "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": "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=20, max=100 | 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=20, max=100 | 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": {}
}
Updated 16 days ago