Users

Data model

User

JSON:API resource type: user.

firstNamestring: First name of the user.
lastNamestring: Last name of the user.
contactEmailstring: The contact email address of the user.

Relationships

clientclient: Client that owns the user. Required. This relationship does NOT grant the user any access to the client (or any of its sub-resources).
readAccessToReportingEntitiesarray of reporting-entity: Reporting entities the user has read access to, i.e. the reporting entities the user can view in MyAleta. Optional.

Invite

JSON:API resource type: 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 supports the following identity providers: Apple, Google, Microsoft.

statestring: Description of the current state of the invite. Possible values: valid, used, expired, cancelled.
linkstring: URL for the invite. This is the link that should be sent to the user.
restrictedToIdentityProviderstring | null: 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). An invite created without a provider has null (no restriction).
restrictedToEmailstring: 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.
expirationstring: ISO 8601 representation of the invite's expiration timestamp. Defaults to 60 days after creation.

Relationships

useruser: The user account the invite grants access to. Required.

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

Create a user

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

firstName, lastName and contactEmail are required; a request without one of them is refused with 400. readAccessToReportingEntities must name at least one reporting entity, and every reporting entity must belong to the client or a client below it; an unknown reporting entity, or one that belongs to another client, is refused with 400. An unknown client returns 404.

When contactEmail belongs to an existing active user, that user is given access instead of a new one being created. An email that belongs to a deactivated user is refused with 409.

Path parameters

idstring: Client identifier, see GET /clients. Required.

Request

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

curl -X POST https://api.aleta.ai/api/v2/clients/6698d912deb64c8b2fec2c08/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "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

{
  "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/api/v2/clients/{id}/users

List users on a client

Find all user accounts owned by the client given by id. Deleted users are not listed. Returns 200, or 404 for an unknown client.

Path parameters

idstring: Client identifier, see GET /clients. Required.

Request

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

curl https://api.aleta.ai/api/v2/clients/6698d912deb64c8b2fec2c08/users \
  -H "Authorization: Bearer {access_token}"

Response

{
  "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/api/v2/users/{id}

Retrieve a user

Find the user account given by id. Returns 200, or 404 when the user does not exist or the caller has no access to the user's client.

Path parameters

idstring: User identifier (a UUID), see GET /clients/:id/users. Required. An id that is not a UUID is refused with 400.

Request

GET/api/v2/users/{id}

curl https://api.aleta.ai/api/v2/users/a3979a79-a8ad-4d14-a83f-ff7b4959c776 \
  -H "Authorization: Bearer {access_token}"

Response

{
  "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/api/v2/users/{id}

Update a user

Update the user account given by id. Returns 200 with the updated user.

All three attributes, firstName, lastName and contactEmail, must be present in attributes; send null for the ones you want to keep. A request without one of them is refused with 400.

readAccessToReportingEntities is optional: when present it replaces the user's reporting entities, when omitted they are kept. An unknown id returns 404.

Path parameters

idstring: User identifier, see GET /clients/:id/users. Required.

Request

PATCH/api/v2/users/{id}

curl -X PATCH https://api.aleta.ai/api/v2/users/a3979a79-a8ad-4d14-a83f-ff7b4959c776 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "id": "a3979a79-a8ad-4d14-a83f-ff7b4959c776",
      "type": "user",
      "attributes": {
        "firstName": null,
        "lastName": "User 1 UPDATED last name",
        "contactEmail": null
      },
      "relationships": {
        "readAccessToReportingEntities": {
          "data": [
            { "type": "reporting-entity", "id": "6852b1535ddc5f5f6e77e85e" }
          ]
        }
      }
    }
  }'

Response

{
  "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/api/v2/users/{id}

Delete a user

Delete the user account given by id. Returns 204 with no body, or 404 for an unknown id. A deleted user is no longer listed on its client, and deleting it again returns 204.

Path parameters

idstring: User identifier, see GET /clients/:id/users. Required.

Request

DELETE/api/v2/users/{id}

curl -X DELETE https://api.aleta.ai/api/v2/users/a3979a79-a8ad-4d14-a83f-ff7b4959c776 \
  -H "Authorization: Bearer {access_token}"

POST/api/v2/users/{id}/invites

Create an invite

Create an invitation link for the user with id. Returns 201.

Path parameters

idstring: User identifier, see GET /clients/:id/users. Required.

Attributes

restrictedToIdentityProviderstring: Optional. Restrict the invite to a single identity provider. Possible values: apple, google, microsoft (lower case); any other non-empty value is refused with 400. This can be used to create a better onboarding experience if the user's preferred identity provider is known.
restrictedToEmailstring: 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.

Request

POST/api/v2/users/{id}/invites

curl -X POST https://api.aleta.ai/api/v2/users/107b590a-3761-4f8f-b776-f8f2fe346e81/invites \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "invite"
    }
  }'

Response

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

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

List invites

Find all invitations created for the user with id, oldest first. This includes both used, expired, cancelled, and valid (active) invites. Returns 200, or 404 for an unknown user. An id that is not a UUID is refused with 400.

Path parameters

idstring: User identifier, see GET /clients/:id/users. Required.

Request

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

curl https://api.aleta.ai/api/v2/users/107b590a-3761-4f8f-b776-f8f2fe346e81/invites \
  -H "Authorization: Bearer {access_token}"

Response

{
  "data": [
    {
      "id": "16f91a30-ca34-42d7-a7c8-2b848c93f54c",
      "type": "invite",
      "attributes": {
        "state": "expired",
        "link": "https://my.aleta.io/-/invite/{token}",
        "restrictedToIdentityProvider": "",
        "restrictedToEmail": "user-contact-email@example.com",
        "expiration": "2024-12-31T11:22:33.123+00:00"
      },
      "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/{token}",
        "restrictedToIdentityProvider": "",
        "restrictedToEmail": "user-contact-email@example.com",
        "expiration": "2025-02-28T11:22:33.123+00:00"
      },
      "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/{token}",
        "restrictedToIdentityProvider": "microsoft",
        "restrictedToEmail": "user-work-email@example.com",
        "expiration": "2025-02-28T11:22:33.123+00:00"
      },
      "relationships": {
        "user": {
          "data": { "type": "user", "id": "107b590a-3761-4f8f-b776-f8f2fe346e81" }
        }
      }
    }
  ]
}

POST/api/v2/users/{userId}/invites/{inviteId}/cancellation

Cancel an invite

Cancel the invitation with inviteId. The invitation link becomes invalid and can no longer be used. Returns 204 with no body. The request body is not read.

The invite is found by inviteId alone. userId must be a UUID but is not compared with the invite's user, so the invite is cancelled whatever user id is in the path.

Only a valid invite can be cancelled: an unknown, used, expired or already cancelled invite is refused with 400. A userId or inviteId that is not a UUID is refused with 400.

If the invited user cannot be found, or you have no write access to that user, the answer is still 204, but nothing is cancelled and the invite stays valid. To confirm a cancellation, check that the invite's state is cancelled in GET /users/:id/invites.

Path parameters

userIdstring: User identifier, see GET /clients/:id/users. Required.
inviteIdstring: Invitation identifier, see GET /users/:id/invites. Required.

Request

POST/api/v2/users/{userId}/invites/{inviteId}/cancellation

curl -X POST \
  https://api.aleta.ai/api/v2/users/107b590a-3761-4f8f-b776-f8f2fe346e81/invites/9c41676f-8b7b-4f8f-9951-2beb73d2bdd4/cancellation \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "invite-cancellation"
    }
  }'