API Organization Endpoints

Endpoints Overview

Method	Path	Auth	Description
GET	/api/organizations	✅	List your organizations
POST	/api/organizations	✅	Create a new organization
GET	/api/organizations/:idOrSlug	✅	Get organization details
PATCH	/api/organizations/:idOrSlug	✅	Update organization
DELETE	/api/organizations/:idOrSlug	✅	Delete organization
GET	/api/organizations/:idOrSlug/members	✅	List members
POST	/api/organizations/:idOrSlug/members	✅	Add a member
PATCH	/api/organizations/:idOrSlug/members/:userId	✅	Update member role
DELETE	/api/organizations/:idOrSlug/members/:userId	✅	Remove member
GET	/api/organizations/:idOrSlug/activity	✅	Get organization activity

All organization endpoints require authentication. The :idOrSlug parameter accepts either a numeric ID or the organization’s URL slug.

List Organizations

GET /api/organizations

Returns all organizations the authenticated user belongs to, regardless of role.

Response

[
  {
    "id": 1,
    "name": "Acme Corp",
    "slug": "acme-corp",
    "role": "owner",
    "memberCount": 5,
    "createdAt": "2026-01-15T10:00:00Z"
  },
  {
    "id": 2,
    "name": "Legal Team",
    "slug": "legal-team",
    "role": "member",
    "memberCount": 3,
    "createdAt": "2026-02-01T08:00:00Z"
  }
]

Create Organization

POST /api/organizations
Content-Type: application/json

Request Body

{
  "name": "Acme Corp",
  "slug": "acme-corp"
}

Parameters

Field	Type	Required	Description
name	string	Yes	Organization display name
slug	string	No	URL-friendly identifier (auto-generated from name if omitted)

The creating user is automatically assigned the owner role.

Get Organization Details

GET /api/organizations/:idOrSlug

Returns full details including name, slug, member count, and credit balances.

{
  "id": 1,
  "name": "Acme Corp",
  "slug": "acme-corp",
  "memberCount": 5,
  "balances": { "IT": 100, "ST": 500, "LG": 5 },
  "createdAt": "2026-01-15T10:00:00Z"
}

Update Organization

PATCH /api/organizations/:idOrSlug
Content-Type: application/json

{
  "name": "Acme Corporation"
}

Requires admin or owner role.

Delete Organization

DELETE /api/organizations/:idOrSlug

Requires owner role. This is irreversible — all organization data, activity history, and member associations are permanently removed.

Member Management

List Members

GET /api/organizations/:idOrSlug/members

[
  {
    "id": 1,
    "walletAddress": "0xabc...",
    "displayName": "Alice",
    "role": "owner",
    "joinedAt": "2026-01-15T10:00:00Z"
  },
  {
    "id": 2,
    "walletAddress": "0xdef...",
    "displayName": "Bob",
    "role": "member",
    "joinedAt": "2026-01-20T14:00:00Z"
  }
]

Add Member

POST /api/organizations/:idOrSlug/members
Content-Type: application/json

{
  "walletAddress": "0xdef...",
  "role": "member"
}

Parameters

Field	Type	Required	Description
walletAddress	string	Yes	Ethereum wallet address of the user to add
role	string	Yes	admin, member, or viewer

The wallet must belong to a registered TimeProof user. Requires admin or owner role in the organization.

Response

{
  "member": {
    "id": 123,
    "walletAddress": "0xdef...",
    "displayName": null,
    "role": "member"
  }
}

Update Member Role

PATCH /api/organizations/:idOrSlug/members/:userId
Content-Type: application/json

{
  "role": "admin"
}

Response

{
  "message": "Role updated successfully",
  "role": "admin"
}

Remove Member

DELETE /api/organizations/:idOrSlug/members/:userId

Requires admin or owner role. The owner cannot be removed.

Role Permissions

Permission	Owner	Admin	Member	Viewer
View organization	✅	✅	✅	✅
Create timestamps	✅	✅	✅	❌
View timestamps	✅	✅	✅	✅
Add members	✅	✅	❌	❌
Remove members	✅	✅	❌	❌
Update roles	✅	✅	❌	❌
Update organization	✅	✅	❌	❌
Delete organization	✅	❌	❌	❌
Purchase credits	✅	✅	❌	❌

Organization Activity

GET /api/organizations/:idOrSlug/activity

Returns the organization’s timestamp history — all jobs created by any member using the organization’s credits.

Integration Example

// Create an organization
const org = await fetch('/api/organizations', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Acme Corp' })
}).then(r => r.json());

// Add a team member
await fetch(`/api/organizations/${org.slug}/members`, {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    walletAddress: '0xdef...',
    role: 'member'
  })
});

// Create a timestamp under the organization
await fetch('/api/timestamps', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    files: [{ name: 'report.pdf', hash: 'sha256...', size: 54321 }],
    creditType: 'ST',
    orgId: org.id
  })
});

Related Guides

• Organizations and Teams — how organizations work in TimeProof
• API Authentication — sign in before managing organizations
• API Credits Endpoints — purchase credits for organizations
• API Timestamp Endpoints — create timestamps under an org