User Access

Choose Your Approach

Approach	Best For	Setup
Entity API Key Access	Simple white-label, no user management	Create entity → Create API key → Redirect
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. No user management required.

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",
});

// Store the key securely - it's only shown once
console.log("API Key:", apiKey.key);

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

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	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