Users

Data Model

User

• firstName (string): First name of the user.
• lastName (string): Last name of the user.
• contactEmail (string): The contact email address of the user.

Relationships

• client (required): Client that owns the user. This relationship does NOT grant the user any access to the client (or any of its sub-resources).

• readAccessToReportingEntities (optional): Reporting entities the user has read access to, i.e. the reporting entities the user can view in MyAleta.

Invite

Invitation link to enable a user to connect a third-party identity to their Aleta user account. Once connected the third-party identity can be used for authentication. MyAleta support following identity providers: Apple, Google, Microsoft.

info

The Aleta API does NOT send the invitation link to user. It is up to caller of the API to send the invitation link to the user. This allows the caller to fully control the communication to user (channel, branding, language, etc.).

• state (string): Description of the current state of the invite. Possible values: "valid", "used", "expired", "cancelled".
• link (string): URL for the invite. This is the link that should be sent to the user.
• restrictedToIdentityProvider (string): The invite may be restricted to a single identity provider. Possible values: "apple", "google", "microsoft", "" (no restriction – the user can select any of the supported identity providers).
• restrictedToEmail (string): The invite is locked to this specific email address. This should match the email address registered by the identity provider (case-insensitive). Defaults to the contact email address of the user when creating the invite.
• expiration (string): ISO 8601 representation of the invite's expiration timestamp. Defaults to 60 days after creation.

Relationships

• user (required): The user account the invite grants access to.

Endpoints

POST /clients/:id/users

Create a user account owned by the client given by id.

Parameters

• id (path, required): Client identifier, see GET /clients.

Examples

201 Created

# Request
POST /api/v2/clients/6698d912deb64c8b2fec2c08/users HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Content-Type: application/vnd.json+api
Host: platform.aleta.io

{
  "data": {
    "type": "user",
    "attributes": {
      "firstName": "New user first name",
      "lastName": "New user last name",
      "contactEmail": "user-contact-email@example.com"
    }
    "relationships": {
      "readAccessToReportingEntities": {
        "data": [
          {
            "type": "reporting-entity",
            "id": "cb4b00eef0af406faddc82ae"
          },
          {
            "type": "reporting-entity",
            "id": "51c10fb37fcada1fbda0eccf"
          }
        ]
      }
    }
  }
}


# Response
HTTP/1.1 201 Created
Content-Type: application/vnd.json+api

{
  "data": {
    "id": "107b590a-3761-4f8f-b776-f8f2fe346e81",
    "type": "user",
    "attributes": {
      "firstName": "New user first name",
      "lastName": "New user last name",
      "contactEmail": "user-contact-email@example.com"
    },
    "relationships": {
      "client": {
        "data": {
          "type": "client",
          "id": "6698d912deb64c8b2fec2c08"
        }
      },
      "readAccessToReportingEntities": {
        "data": [
          {
            "type": "reporting-entity",
            "id": "cb4b00eef0af406faddc82ae"
          },
          {
            "type": "reporting-entity",
            "id": "51c10fb37fcada1fbda0eccf"
          }
        ]
      }
    }
  }
}

GET /clients/:id/users

Find all user accounts owned by the client given by id.

Parameters

• id (path, required): Client identifier, see GET /clients.

Examples

200 OK

# Request
GET /api/v2/clients/6698d912deb64c8b2fec2c08/users HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Content-Type: application/vnd.json+api
Host: platform.aleta.io

# Response
HTTP/1.1 200 OK
Content-Type: application/vnd.json+api

{
  "data": [
    {
      "id": "a3979a79-a8ad-4d14-a83f-ff7b4959c776",
      "type": "user",
      "attributes": {
        "firstName": "User 1 first name",
        "lastName": "User 1 last name",
        "contactEmail": "user1-contact-email@example.com"
      },
      "relationships": {
        "client": {
          "data": {
            "type": "client",
            "id": "6698d912deb64c8b2fec2c08"
          }
        },
        "readAccessToReportingEntities": {
          "data": [
            {
              "type": "reporting-entity",
              "id": "cb4b00eef0af406faddc82ae"
            },
            {
              "type": "reporting-entity",
              "id": "51c10fb37fcada1fbda0eccf"
            }
          ]
        }
      }
    },
    {
      "id": "87f024aa-d0fe-43fd-8240-7a2c45eef947",
      "type": "user",
      "attributes": {
        "firstName": "User 2 first name",
        "lastName": "User 2 last name",
        "contactEmail": "user2-contact-email@example.com"
      },
      "relationships": {
        "client": {
          "data": {
            "type": "client",
            "id": "6698d912deb64c8b2fec2c08"
          }
        },
        "readAccessToReportingEntities": {
          "data": [
            {
              "type": "reporting-entity",
              "id": "cb4b00eef0af406faddc82ae"
            }
          ]
        }
      }
    }
  ]
}

GET /users/:id

Find the user account given by id.

Parameters

• id (path, required): User identifier, see GET /clients/:id/users.

Examples

200 OK

# Request
GET /api/v2/users/a3979a79-a8ad-4d14-a83f-ff7b4959c776 HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Host: platform.aleta.io


# Response
HTTP/1.1 200 OK
Content-Type: application/vnd.json+api

{
  "data": {
    "id": "a3979a79-a8ad-4d14-a83f-ff7b4959c776",
    "type": "user",
    "attributes": {
      "firstName": "User 1 first name",
      "lastName": "User 1 last name",
      "contactEmail": "user1-contact-email@example.com"
    },
    "relationships": {
      "client": {
        "data": {
          "type": "client",
          "id": "6698d912deb64c8b2fec2c08"
        }
      },
      "readAccessToReportingEntities": {
        "data": [
          {
            "type": "reporting-entity",
            "id": "cb4b00eef0af406faddc82ae"
          },
          {
            "type": "reporting-entity",
            "id": "51c10fb37fcada1fbda0eccf"
          }
        ]
      }
    }
  }
}

PATCH /users/:id

Update the user account given by id.

Parameters

• id (path, required): User identifier, see GET /clients/:id/users.

Examples

200 OK

# Request
GET /api/v2/users/a3979a79-a8ad-4d14-a83f-ff7b4959c776 HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Host: platform.aleta.io

{
  "data": {
    "id": "a3979a79-a8ad-4d14-a83f-ff7b4959c776",
    "type": "user",
    "attributes": {
      "lastName": "User 1 UPDATED last name"
    }
    "relationships": {
      "readAccessToReportingEntities": {
        "data": [
          {
            "type": "reporting-entity",
            "id": "6852b1535ddc5f5f6e77e85e"
          }
        ]
      }
    }
  }
}


# Response
HTTP/1.1 200 OK
Content-Type: application/vnd.json+api

{
  "data": {
    "id": "a3979a79-a8ad-4d14-a83f-ff7b4959c776",
    "type": "user",
    "attributes": {
      "firstName": "User 1 first name",
      "lastName": "User 1 UPDATED last name",
      "contactEmail": "user1-contact-email@example.com"
    },
    "relationships": {
      "client": {
        "data": {
          "type": "client",
          "id": "6698d912deb64c8b2fec2c08"
        }
      },
      "readAccessToReportingEntities": {
        "data": [
          {
            "type": "reporting-entity",
            "id": "6852b1535ddc5f5f6e77e85e"
          }
        ]
      }
    }
  }
}

DELETE /users/:id

Delete the user account given by id.

Parameters

• id (path, required): User identifier, see GET /clients/:id/users.

Examples

204 No Content

# Request
DELETE /api/v2/users/a3979a79-a8ad-4d14-a83f-ff7b4959c776 HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Host: platform.aleta.io


# Response
HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json

POST /users/:id/invites

Create an invitation link for the user with id.

Parameters

• id (path, required): User identifier, see GET /clients/:id/users.
• restrictedToIdentityProvider (string, optional): Restrict the invite to a single identity provider. Possible values: "apple", "google", "microsoft". This can be used to create a better onboarding experience if the user's preferred identity provider is known.
• restrictedToEmail (string, optional): By default the invite is locked to the contact email address of the user. This optional field can be used to override the default. This can be useful if the user wants an additional identity connected, e.g. a private Apple identity or a work Microsoft identity.

Examples

Standard invite (user's contact email address)

201 Created

# Request
POST /api/v2/users/107b590a-3761-4f8f-b776-f8f2fe346e81/invites HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Content-Type: application/vnd.json+api
Host: platform.aleta.io

{
  "data": {
    "type": "invite"
  }
}


# Response
HTTP/1.1 201 Created
Content-Type: application/vnd.json+api

{
  "data": {
    "id": "d0a4d3fe-4309-47e3-b677-9c89ca1c1e73",
    "type": "invite",
    "attributes": {
      "state": "valid",
      "link": "https://my.aleta.io/-/invite/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiMTIzIn0.FIUplmSwpwqNA-_Fq-MEFBYrAXb-jQJe-Qyy26UKAeo",
      "restrictedToIdentityProvider": "",
      "restrictedToEmail": "user-contact-email@example.com",
      "expiration": "2025-02-28T11:22:33.123Z"
    },
    "relationships": {
      "user": {
        "data": {
          "type": "user",
          "id": "107b590a-3761-4f8f-b776-f8f2fe346e81"
        }
      }
    }
  }
}

Customized invite

201 Created

# Request
POST /api/v2/users/107b590a-3761-4f8f-b776-f8f2fe346e81/invites HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Content-Type: application/vnd.json+api
Host: platform.aleta.io

{
  "data": {
    "type": "invite",
    "attributes": {
      "restrictedToIdentityProvider": "microsoft",
      "restrictedToEmail": "user-work-email@example.com"
    }
  }
}


# Response
HTTP/1.1 201 Created
Content-Type: application/vnd.json+api

{
  "data": {
    "id": "9c41676f-8b7b-4f8f-9951-2beb73d2bdd4",
    "type": "invite",
    "attributes": {
      "state": "valid",
      "link": "https://my.aleta.io/-/invite/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiNDU2In0.nobHyiBSTS4Qj24UyelPjWd6rDXNRVaH4L5-F7qxZrQ",
      "restrictedToIdentityProvider": "microsoft",
      "restrictedToEmail": "user-work-email@example.com",
      "expiration": "2025-02-28T11:22:33.123Z"
    },
    "relationships": {
      "user": {
        "data": {
          "type": "user",
          "id": "107b590a-3761-4f8f-b776-f8f2fe346e81"
        }
      }
    }
  }
}

GET /users/:id/invites

Find all invitations created for the user with id. This includes both used, expired, cancelled, and valid (active) invites.

Find all invitations created for the user with id. This includes both used, expired, cancelled, and valid (active) invites.

Parameters

• id (path, required): User identifier, see GET /clients/:id/users.

Examples

200 OK

# Request
GET /api/v2/users/107b590a-3761-4f8f-b776-f8f2fe346e81/invites HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Content-Type: application/vnd.json+api
Host: platform.aleta.io

# Response
HTTP/1.1 200 OK
Content-Type: application/vnd.json+api

{
  "data": [
    {
      "id": "16f91a30-ca34-42d7-a7c8-2b848c93f54c",
      "type": "invite",
      "attributes": {
        "state": "expired",
        "link": "https://my.aleta.io/-/invite/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiNzg5In0.O4N--yxpxzvL3-TClWucvBIfRiOT9nqXbCXA8zkXWyk",
        "restrictedToIdentityProvider": "",
        "restrictedToEmail": "user-contact-email@example.com",
        "expiration": "2024-12-31T11:22:33.123Z"
      },
      "relationships": {
        "user": {
          "data": {
            "type": "user",
            "id": "107b590a-3761-4f8f-b776-f8f2fe346e81"
          }
        }
      }
    },
    {
      "id": "d0a4d3fe-4309-47e3-b677-9c89ca1c1e73",
      "type": "invite",
      "attributes": {
        "state": "used",
        "link": "https://my.aleta.io/-/invite/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiMTIzIn0.FIUplmSwpwqNA-_Fq-MEFBYrAXb-jQJe-Qyy26UKAeo",
        "restrictedToIdentityProvider": "",
        "restrictedToEmail": "user-contact-email@example.com",
        "expiration": "2025-02-28T11:22:33.123Z"
      },
      "relationships": {
        "user": {
          "data": {
            "type": "user",
            "id": "107b590a-3761-4f8f-b776-f8f2fe346e81"
          }
        }
      }
    },
    {
      "id": "9c41676f-8b7b-4f8f-9951-2beb73d2bdd4",
      "type": "invite",
      "attributes": {
        "state": "valid",
        "link": "https://my.aleta.io/-/invite/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleGFtcGxlIjoiNDU2In0.nobHyiBSTS4Qj24UyelPjWd6rDXNRVaH4L5-F7qxZrQ",
        "restrictedToIdentityProvider": "microsoft",
        "restrictedToEmail": "user-work-email@example.com",
        "expiration": "2025-02-28T11:22:33.123Z"
      },
      "relationships": {
        "user": {
          "data": {
            "type": "user",
            "id": "107b590a-3761-4f8f-b776-f8f2fe346e81"
          }
        }
      }
    },
  ]
}

POST /users/:userId/invites/:inviteId/cancellation

Cancel the invitation with inviteId for user userId. The invitation link becomes invalid and can no longer be used.

Parameters

• userId (path, required): User identifier, see GET /clients/:id/users.
• inviteId (path, required): Invitation identifier, see GET /users/:id/invites.

Examples

204 No Content

# Request
POST /api/v2/users/107b590a-3761-4f8f-b776-f8f2fe346e81/invites/9c41676f-8b7b-4f8f-9951-2beb73d2bdd4/cancellation HTTP/1.1
Accept: application/vnd.json+api
Authorization: Bearer <access token>
Host: platform.aleta.io

{
  "data": {
    "type": "invite-cancellation"
  }
}

# Response
HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json