Retrieving your Lumar accounts
To begin fully using the API you will need access to account with an active subcription.
To find out which accounts do you have access to you can run following GraphQL query.
query getMyAccounts {
me {
accounts(first: 5) {
nodes {
id
name
}
}
}
}
When you have an account id that you want to access to you can skip going through me and query directly to get a specific account.
query getAccountNode($accountId: ObjectID!) {
node(id: $accountId) {
... on Account {
id
name
}
}
}
or you can use getAccount query.
query getSpecificAccount($accountId: ObjectID!) {
getAccount(id: $accountId) {
... on Account {
id
name
}
}
}
App access
Two things decide which Lumar apps a person can open: what the account's subscription includes, and what an administrator has granted that individual user.
subscription.availableApps lists the apps the account itself is entitled to, named the same way as the per-user field below, so you do not have to know which of the *Available booleans corresponds to which app.
query GetAccountAvailableApps($accountId: ObjectID!) {
getAccount(id: $accountId) {
subscription {
availableApps
}
}
}
Alongside a role, each membership then carries the set of apps that user may open. Read it from apps on Account.accountUsers.
query GetAccountUserApps($accountId: ObjectID!) {
getAccount(id: $accountId) {
accountUsers(first: 20) {
nodes {
userId
userEmail
roleCode
apps
}
}
}
}
An empty apps list means the user is unrestricted — they can open everything in availableApps. It does not mean the user is locked out of everything. Only once an administrator sets one or more apps do clients narrow what they show.
Account administrators change the list with updateAccountUser. The field replaces the whole set: pass the complete list of apps the user should keep, or an empty list to lift the restriction entirely. Omit apps to change only the role and leave app access untouched.
mutation UpdateAccountUserApps($input: UpdateAccountUserInput!) {
updateAccountUser(input: $input) {
account {
accountUsers(first: 20) {
nodes {
userId
apps
}
}
}
}
}
addAccountUser takes the same field, so a new user can be invited with their app list already set instead of being created unrestricted and narrowed by a second call. Omit it there to leave them unrestricted.
mutation AddAccountUser($input: AddAccountUserInput!) {
addAccountUser(input: $input) {
account {
accountUsers(first: 20) {
nodes {
userEmail
roleCode
apps
}
}
}
}
}
Defaults for SSO users
Users provisioned through SSO never pass through addAccountUser, so they get their app list from the connection instead. defaultApps on createSsoConnection / updateSsoConnection sets it, alongside the defaultRoleCode that works the same way for roles.
mutation UpdateSsoConnectionDefaultApps($input: UpdateSsoConnectionInput!) {
updateSsoConnection(input: $input) {
ssoConnection {
defaultRoleCode
defaultApps
}
}
}
The default is copied onto a membership when that membership is first created, and never re-applied. Two consequences worth designing around:
- An administrator's later edit to an individual user survives every subsequent login. Roles behave differently — those are recomputed from the group mappings on each login, because a group change has to be able to take privileges away.
- Changing
defaultAppsaffects users provisioned from then on. Anyone who already has a membership keeps the list they have; update them withupdateAccountUser.
Leave defaultApps unset, or pass an empty list to clear it, and new SSO users land unrestricted — which is how every SSO connection behaves today.
App access is presentation guidance, not an authorization boundary. Lumar's own apps use it to decide what to put in the app switcher and navigation, and you can use it the same way. The API does not enforce it: every request is still authorized by the user's role, the account they are acting on, and the account's subscription — a user restricted to Monitor can still call an Analyze query if their role allows it. Do not rely on this field to keep anyone out of data.
Seat limits
An account's subscription caps how many users may be connected to it. Two fields on Account report the numbers the API itself enforces:
usersLimit-- the maximum number of users the account may hold. This is0when the account's package sells no seats;0never means "unlimited".usersCount-- the users currently connected to the account, which is whatusersLimitis compared against. Pending user invites are not counted, so seats already promised to open invites still read as free.
Gate an "invite user" action on usersCount < usersLimit rather than deriving the limit from accountSettings: once the two numbers meet, connecting another user through the API fails with ACCOUNT_USER_LIMIT_REACHED.
Users provisioned by SSO login are added outside this check, so on an SSO account usersCount may exceed usersLimit. Read the remaining seats as max(0, usersLimit - usersCount).