Authentication Behavior Patterns

How different authentication methods affect API access and data visibility.

---

Overview

The Arkipel API supports multiple authentication methods, and each endpoint may behave differently depending on the method used. This document explains the common authentication patterns and how they affect query results and mutations.

For general authentication setup (keypair vs API token), see API Connection.

---

Authentication Methods

The API recognizes three authentication categories:

1. Account-Based Authentication

Methods:

• API Token - Bearer token provided by the community administrator
• Whitelist (Organization) - Keypair associated with an organization

Characteristics:

• Full account access
• Can query/modify any data in the account
• No automatic filtering applied
• Suitable for integrations, background jobs, administrative tools

2. Person-Scoped Authentication

Methods:

• Whitelist (Person) - Keypair associated with a specific person
• Membership - Internal user membership authentication

Characteristics:

• Access limited to the authenticated person’s data
• Queries automatically filter to show only relevant records
• Mutations restricted to person’s own records
• Suitable for personal access, mobile apps, individual portals

3. Universal Access

Some endpoints don’t filter by authentication method - all authenticated users see the same data.

---

Common Behavior Patterns

Pattern A: Full Account Access (No Filtering)

Applies to: Notes queries, person_categories queries, household_categories queries

Behavior:

Auth Method	Data Visibility
API Token	All account data
Whitelist (Person)	All account data
Whitelist (Organization)	All account data
Membership	All account data

Override Parameters:

None - all auth methods see the same data.

---

Pattern B: Person-Scoped by Default

Applies to: Todos queries, todo mutations

Behavior:

Auth Method	Data Visibility
API Token	All account todos
Whitelist (Person)	Only that person’s todos
Whitelist (Organization)	All account todos
Membership	Only that person’s todos

Override Parameters:

• all_assignees: true - Returns all todos regardless of auth method (requires CLI/agent context)
• person_id_eq: N - Explicitly filter by person ID (takes precedence over automatic filtering)

Use Case:

Personal todo lists where individuals should only see their own tasks, but administrators/integrations can see all.

---

Pattern C: Ownership-Based Access

Applies to: Single resource queries (todo:query, note:query)

Behavior:

Auth Method	Access
API Token	Any resource in account
Whitelist (Person)	Any resource in account
Whitelist (Organization)	Any resource in account
Membership	Only resources associated with the person

Error Response:

• Membership auth attempting to access other persons’ resources: 403 Forbidden

Use Case:

Direct resource access where membership-based clients have restricted visibility.

---

Endpoint Reference

Endpoint	Pattern	Override Parameters
todos:query	B - Person-Scoped	all_assignees, person_id_eq
todo:query	C - Ownership	None (returns 403 if unauthorized)
todo:close	C - Ownership	None
todo:reopen	C - Ownership	None
notes:query	A - Full Access	None
note:query	A - Full Access	None
people:query	A - Full Access	None
person:query	A - Full Access	None

Note: Most query endpoints follow Pattern A (Full Access). Check individual spec pages for endpoint-specific behavior.

---

Implementation Examples

CLI Agent with Full Access

{
  "type": "todos:query",
  "q": {
    "all_assignees": true,
    "completed_at_null": true
  }
}

Personal App (Default Filtering)

{
  "type": "todos:query",
  "q": {
    "due_period": "today"
  }
}

// Returns only the authenticated person’s todos

Explicit Person Filter

{
  "type": "todos:query", 
  "q": {
    "person_id_eq": 123,
    "completed_at_null": true
  }
}

// Returns todos for person 123 regardless of auth method

---

Error Codes

403 Forbidden

Returned when person-scoped authentication attempts to access unauthorized resources:

{
  "error": "Forbidden: You can only access your own todos"
}

Resolution

• Use account-based authentication (API token)
• Add all_assignees: true parameter (if supported)
• Request access to the specific person’s data

---

Related Documentation

• API Connection - Authentication setup and configuration
• Error Handling - Common error responses and solutions
• Individual spec pages for endpoint-specific behavior

---

Return to API Specifications