@uptodateapps/auth-sdk

TypeScript SDK for integrating with accounts.uptodateconnect.com. Compatible with Node.js 16+ and all browsers (Vue, React, etc.).

Install

npm install @uptodateapps/auth-sdk

Setup

import { UpToDateAuth } from '@uptodateapps/auth-sdk'

const auth = new UpToDateAuth({
  baseUrl: 'https://accounts.uptodateconnect.com',
  apiKey: 'svc_...',               // admin panel → Services → your service → API Key
  serviceSlug: 'your-service-slug', // the @slug shown in the admin panel
  fetch: window.fetch.bind(window), // required in browser; omit in Node.js 18+
})

auth.users

auth.users.getAccess(email) ⭐

The main method. Returns every company the user belongs to, their company role, every website in those companies, and their role + permissions on each — all from just an email.

const { user, companies } = await auth.users.getAccess('[email protected]')

for (const company of companies) {
  console.log(`${company.name} — role: ${company.userRole}, isAdmin: ${company.isAdmin}`)

  for (const site of company.websites) {
    if (site.hasAccess) {
      console.log(`  ${site.domain} → ${site.role} [via ${site.source}]`)
      console.log(`  permissions: ${site.permissions.join(', ')}`)
    }
  }
}

Response shape:

{
  user: { id, email, displayName, systemRole },
  companies: [
    {
      id, name, slug, logoUrl,
      userRole: 'OWNER' | 'ADMIN' | 'MEMBER' | ...,
      isAdmin: boolean,
      websites: [
        {
          id, name, slug, domain, logoUrl, status,
          role: 'MANAGER' | 'EDITOR' | 'AUTHOR' | 'REPORTER' | 'AI_USER' | null,
          permissions: string[],
          source: 'company_admin' | 'website_member' | 'custom_role' | 'team_access' | 'none',
          hasAccess: boolean
        }
      ]
    }
  ]
}

auth.users.sync(input)

Create or update a user. Matched by email.

await auth.users.sync({
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Doe',
  displayName: 'Jane Doe',   // optional
  avatarUrl: '...',          // optional
  externalId: 'your_id_123', // optional
})
// { user: { id, email }, created: boolean }

auth.users.syncBulk(users[])

Sync up to 100 users at once.

const result = await auth.users.syncBulk([
  { email: '[email protected]', firstName: 'A' },
  { email: '[email protected]', firstName: 'B' },
])
// { summary: { total, created, updated, failed }, created[], updated[], failed[] }

auth.users.findByEmail(email)

Look up a user profile.

const user = await auth.users.findByEmail('[email protected]')
// { id, email, firstName, lastName, displayName, avatarUrl, status, createdAt }

auth.permissions

auth.permissions.forUser({ token, companyId }) ⭐

Use this to gate features. Verifies the user's JWT and resolves their permissions for your service — including custom roles assigned in the accounts panel.

const { can, canAll, canAny, user, permissions, accessSource } =
  await auth.permissions.forUser({
    token: userJwt,       // the user's JWT access token
    companyId: 'cmp_xxx', // company context
  })

if (can('dashboard.analytics'))               { /* show analytics */ }
if (canAll(['docs.read', 'docs.create']))      { /* show editor */ }
if (canAny(['admin.*', 'settings.manage']))    { /* show settings */ }

console.log(accessSource)
// 'custom_role' | 'company_override' | 'service_default' | 'user_direct' | 'public_defaults'

auth.permissions.verify(options)

Same as forUser but returns raw result without helper methods.

const result = await auth.permissions.verify({
  token: userJwt,
  companyId: 'cmp_xxx',
  requiredPermissions: ['dashboard.read'], // optional
})
// result.authorized         — true/false
// result.permissions        — full resolved permission list
// result.missingPermissions — what's missing (if any)
// result.accessSource       — how it was resolved

auth.permissions.check(email, domain, permission?)

Check a user's role + permissions on a specific website by domain.

const result = await auth.permissions.check('[email protected]', 'mysite.com')
// result.role        — 'EDITOR'
// result.permissions — ['content.read', 'content.create', ...]
// result.isAdmin     — false
// result.source      — 'website_member'

// with specific permission check:
const result = await auth.permissions.check('[email protected]', 'mysite.com', 'content.create')
// result.hasPermission — true | false

auth.permissions.hasPermission(email, domain, permission)

Returns just the boolean.

const ok = await auth.permissions.hasPermission('[email protected]', 'mysite.com', 'content.create')
// true | false

auth.permissions.checkBatch(domain, emails[])

Check up to 100 users on one website at once.

const result = await auth.permissions.checkBatch('mysite.com', [
  '[email protected]',
  '[email protected]',
])
// result.results[] — [{ email, role, permissions, source, hasAccess }]

auth.websites

auth.websites.sync(input)

Create or update a website. Matched by domain within the company.

await auth.websites.sync({
  domain: 'mysite.com',
  name: 'My Site',
  companySlug: 'my-company',
})
// { website: { id, domain, slug }, created: boolean }

auth.websites.syncBulk(websites[])

Sync up to 50 websites at once.

auth.websites.findByDomain(domain)

const website = await auth.websites.findByDomain('mysite.com')
// { id, name, slug, domain, status, visibility, company, createdAt }

auth.members

auth.members.assign(domainOrId, input)

Assign a role to a user on a website. Creates or updates the membership.

await auth.members.assign('mysite.com', {
  userEmail: '[email protected]',
  role: 'EDITOR', // MANAGER | EDITOR | AUTHOR | REPORTER | AI_USER
})
// { membership: { id, role }, created: boolean }

auth.members.assignBulk(domainOrId, members[])

Assign roles to up to 100 users at once.

const result = await auth.members.assignBulk('mysite.com', [
  { userEmail: '[email protected]', role: 'EDITOR' },
  { userEmail: '[email protected]', role: 'AUTHOR' },
])
// result.summary — { total, assigned, failed }

auth.members.list(domainOrId)

const result = await auth.members.list('mysite.com')
// result.members[] — [{ id, role, joinedAt, user: { id, email, firstName, ... } }]

auth.members.remove(domainOrId, userEmail)

await auth.members.remove('mysite.com', '[email protected]')

auth.verify(options)

Top-level shortcut — same as auth.permissions.verify().

const result = await auth.verify({ token, companyId })

auth.can(permissions, permission)

Utility to check a permission against a resolved list. Supports wildcards.

auth.can(['dashboard.*'], 'dashboard.analytics') // true
auth.can(['*'], 'anything')                       // true
auth.can(['docs.read'], 'docs.create')            // false

Permission resolution order

When forUser / verify is called, permissions resolve in this order:

| Priority | Source | accessSource value | |---|---|---| | 1 | Super Admin | returns ['*'] | | 2 | Direct user grant | 'user_direct' | | 3 | Company role override | 'company_override' | | 4 | Service default role mapping | 'service_default' | | 5 | Custom role assignment | 'custom_role' | | 6 | Public service defaults | 'public_defaults' |

Changelog

1.2.0

• Added auth.users.getAccess(email) — returns full company + website + permissions tree from just an email
• Added UserAccessResult, UserAccessCompany, UserAccessWebsite types

1.1.0

• Added serviceSlug to config (now required)
• Added auth.verify() and auth.can()
• Added auth.permissions.verify() and auth.permissions.forUser()
• Added VerifyResult, VerifyOptions, PermissionChecker types

1.0.1

• Initial release: users, websites, members, permissions namespaces