User Access

Choose Your Approach

Approach	Best For	Setup
Entity API Key Access	Simple white-label, no user management	Create entity → Create API key → Generate server-side launch flow
User-Based Access	Role-based permissions, team collaboration	Create entity → Add users → Generate tokens

Entity API Key Access

The simplest way to give your customers dashboard access when you do not want to manage Space Invoices user records.

How It Works

API key access structure

┌───────────────────────────────────────────────┐
│              Your Application                 │
├───────────────────────────────────────────────┤
│  API Key (entity-scoped)                      │
│  ─────────────────────────                    │
│  Access: Single entity only                   │
│  Use: Backend integrations                    │
├───────────────────────────────────────────────┤
│  Invoices  │  Customers  │  Items             │
└────────────┴─────────────┴────────────────────┘

Setup

1. Create an entity for your customer:

Create entitytypescript

// title: Create an entity
const _entity = await sdk.entities.create({
  name: "My Company",
  address: "123 Business Street",
  city: "Ljubljana",
  zip: "1000",
  country: "Slovenia",
  taxNumber: "SI12345678",
  taxSubject: true,
});

2. Create an entity API key:

Create api keytypescript

// title: Create API key for entity
const _apiKey = await sdk.entityApiKeys.create(entity.id, {
  name: "Production API Key",
  environment: "production",
});

3. Redirect to dashboard:

Redirect api keytypescript

// title: Use API key in requests
import { SpaceInvoices } from "@spaceinvoices/js-sdk";

// Initialize SDK with entity API key
const sdk = new SpaceInvoices({
  apiKey: process.env.ENTITY_API_KEY,
});

// All requests are automatically scoped to the entity
const _invoices = await sdk.invoices.list();

Key Points

No user records — You don’t manage Space Invoices users
Full entity access — API key grants complete access to the entity
Environment-specific — Key inherits entity’s environment (live/sandbox)
One key per entity — Create additional keys if needed for different purposes
Server-side only — Keep the key private and use your backend to initiate access

Integration Flow

API key authentication flow

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│   Your       │     │   Your Server   │     │    Space     │
│   System     │────▶│   (Backend)     │────▶│   Invoices   │
└──────────────┘     └─────────────────┘     └──────────────┘
                            │                       │
                            │  Authorization:       │
                            │  Bearer <api_key>     │
                            │─────────────────────▶│
                            │                       │
                            │  API Response         │
                            │◀─────────────────────│
                            │                       │

User-Based Access

For platforms that need role-based permissions or team collaboration within entities.

How It Works

User-based access structure

┌───────────────────────────────────────────────┐
│                    Entity                     │
├───────────────────────┬───────────────────────┤
│   User A (admin)      │   User B (member)     │
│   Full access         │   Limited access      │
├───────────────────────┴───────────────────────┤
│  Invoices  │  Customers  │  Settings          │
└────────────┴─────────────┴────────────────────┘

User Roles

Role	Permissions
`viewer`	Read-only access to invoices, customers, etc.
`editor`	Create and edit invoices, customers, items
`admin`	Full access including settings, users, API keys

Setup

1. Create an entity for your customer:

Create entitytypescript

// title: Create an entity
const _entity = await sdk.entities.create({
  name: "My Company",
  address: "123 Business Street",
  city: "Ljubljana",
  zip: "1000",
  country: "Slovenia",
  taxNumber: "SI12345678",
  taxSubject: true,
});

2. Add users to the entity:

Add userstypescript

// title: Add users to entity
// Add an admin user
await sdk.entityUsers.add(entity.id, {
  email: "admin@company.com",
  role: "admin",
});

// Add a team member
await sdk.entityUsers.add(entity.id, {
  email: "team@company.com",
  role: "member",
});

3. Generate SSO token and redirect:

Generate tokentypescript

// title: Generate user access token
const token = await sdk.entityUsers.generateToken(entity.id, user.id);

// Use token to access embedded dashboard
const _dashboardUrl = `https://app.spaceinvoices.com/embed?token=${token}`;

Key Points

Role-based access — Control what each user can do
Team collaboration — Multiple users per entity with different roles
User management — Users have Space Invoices accounts
Cross-entity access — One user can access multiple entities

Integration Flow

User authentication flow

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│   User       │     │   Your App      │     │    Space     │
│   Logs In    │────▶│   Backend       │────▶│   Invoices   │
└──────────────┘     └─────────────────┘     └──────────────┘
                            │                       │
                            │  1. Generate token    │
                            │─────────────────────▶│
                            │                       │
                            │  2. Redirect to embed │
                            │◀─────────────────────│
                            │                       │
                            │  3. User accesses UI  │
                            │─────────────────────▶│
                            │                       │

Choosing the Right Approach

Scenario	Recommended
Simple white-label dashboard with server-brokered access	Entity API Key Access
Multiple team members need access	User-Based Access
Different permission levels needed	User-Based Access
Minimal setup, fast integration	Entity API Key Access
Users need to access multiple entities	User-Based Access
Automated systems (no UI)	Entity API Keys for API calls

Next Steps

Entity API Keys API — Create and manage entity API keys
Entity Users API — Manage users on entities
Entity Invitations API — Invitation management
Multi-Tenancy — Entity management basics