View as Markdown

Users

Users are the humans who access a client's data — family members, advisors, accountants, external partners. Every user belongs to a client, and read access is granted at the reporting-entity level so a single user can see consolidated views without being given the run of the underlying ledger. Invitations carry their own lifecycle so access can be granted, restricted to a specific identity provider, and revoked with an audit trail.

Data model

User

JSON:API resource type: user.

  • Name
    id
    Type
    string
    Description

    Stable identifier for the user.

  • Name
    firstName
    Type
    string
    Description

    Given name. Free-form.

  • Name
    lastName
    Type
    string
    Description

    Family name. Free-form.

  • Name
    contactEmail
    Type
    string
    Description

    Email used for invites and notifications. Note that the email a user actually signs in with is determined by their identity provider — contactEmail is the address Aleta corresponds with.

Relationships

  • Name
    readAccessToReportingEntities
    Type
    array of reporting-entity
    Description

    The reporting entities this user can read. Updated through PATCH /api/v2/users/{id} by replacing the relationship array.

Invite

JSON:API resource type: invite. Invites are short-lived handles on a pending login. Once the user completes the identity-provider flow the invite is consumed and they become an active user on the client.

  • Name
    id
    Type
    string
    Description

    Invite identifier.

  • Name
    identityProvider
    Type
    enum
    Description

    Optional. Restricts the invite to a single provider — one of microsoft, google, apple. Omitted when any provider is acceptable.

  • Name
    email
    Type
    string
    Description

    Optional. Restricts the invite to a single email address — the user must sign in with this address at the identity provider.

  • Name
    cancelledAt
    Type
    timestamp | null
    Description

    Set when the invite is cancelled before acceptance.

GET/api/v2/clients/{id}/users

List users on a client

Returns every user with any access to the client, including those who have been invited but haven't yet completed sign-in.

Request

GET/api/v2/clients/{id}/users
curl https://platform.aleta.io/api/v2/clients/{client_id}/users \
  -H "Authorization: Bearer {access_token}"
GET/api/v2/users/{id}

Retrieve a user

Fetches a single user record, including the readAccessToReportingEntities relationship.

Request

GET/api/v2/users/{id}
curl https://platform.aleta.io/api/v2/users/{id} \
  -H "Authorization: Bearer {access_token}"
POST/api/v2/clients/{id}/users

Create a user

Creates a user record under the client. Creation does not send an invite by itself — call the invites endpoint afterwards to email the sign-in link. The grant of readAccessToReportingEntities can be set at creation time.

Request

POST/api/v2/clients/{id}/users
curl -X POST https://platform.aleta.io/api/v2/clients/{client_id}/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "user",
      "attributes": {
        "firstName": "Anna",
        "lastName": "Andersen",
        "contactEmail": "anna@example.com"
      },
      "relationships": {
        "readAccessToReportingEntities": {
          "data": [
            { "type": "reporting-entity", "id": "{reporting_entity_id}" }
          ]
        }
      }
    }
  }'
PATCH/api/v2/users/{id}

Update a user

Patches name, contact email, or the readAccessToReportingEntities relationship. Replacing the relationship array fully overrides the previous grant — pass the entire desired set.

Request

PATCH/api/v2/users/{id}
curl -X PATCH https://platform.aleta.io/api/v2/users/{id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "user",
      "id": "{id}",
      "attributes": { "contactEmail": "anna.new@example.com" }
    }
  }'
DELETE/api/v2/users/{id}

Delete a user

Removes the user record and revokes their access. Pending invites are invalidated as part of the same call.

Request

DELETE/api/v2/users/{id}
curl -X DELETE https://platform.aleta.io/api/v2/users/{id} \
  -H "Authorization: Bearer {access_token}"
POST/api/v2/users/{id}/invites

Send an invite

Creates an invite for the user and triggers delivery of the sign-in email. Pin the invite to a specific identity provider (microsoft, google, apple) and/or email by setting those attributes; omit them to accept any provider/email matching the identity-provider claim.

Request

POST/api/v2/users/{id}/invites
curl -X POST https://platform.aleta.io/api/v2/users/{user_id}/invites \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "invite",
      "attributes": {
        "identityProvider": "microsoft",
        "email": "anna@example.com"
      }
    }
  }'
GET/api/v2/users/{id}/invites

List invites

Returns every invite ever issued to the user — pending, accepted, and cancelled. Useful for auditing access history.

Request

GET/api/v2/users/{id}/invites
curl https://platform.aleta.io/api/v2/users/{user_id}/invites \
  -H "Authorization: Bearer {access_token}"
POST/api/v2/users/{userId}/invites/{inviteId}/cancellation

Cancel an invite

Marks the invite as cancelled and invalidates the email link. Idempotent — re-inviting the user creates a fresh record rather than reversing the cancellation.

Request

POST/api/v2/users/{userId}/invites/{inviteId}/cancellation
curl -X POST \
  https://platform.aleta.io/api/v2/users/{user_id}/invites/{invite_id}/cancellation \
  -H "Authorization: Bearer {access_token}"