Organizations API

The Organizations API provides endpoints for managing organizations, teams, and organization-level settings in Providence.

Overview

Organizations in Providence:

Container for projects: Each organization can have multiple projects
User management: Control who has access to your data
Team structure: Organize users into teams
Billing unit: Usage and billing tracked at organization level
Settings & policies: Organization-wide configurations

Authentication

All organization endpoints require authentication via JWT token:

Authorization: Bearer <your-jwt-token>

Some endpoints require specific organization roles:

Owner: Full control over organization
Admin: Manage users, teams, and settings
Member: View organization details

Endpoints

List Organizations

Get all organizations the authenticated user belongs to.

GET /api/v1/organizations

Parameters

Name	Type	Location	Required	Description
page	integer	query	No	Page number (default: 1)
limit	integer	query	No	Items per page (default: 20)
role	string	query	No	Filter by user role: owner, admin, member

Response

{
  "organizations": [
    {
      "id": "org_abc123def456",
      "name": "Acme Corporation",
      "slug": "acme-corp",
      "description": "Leading provider of innovative solutions",
      "logo_url": "https://assets.providence.io/orgs/acme-corp/logo.png",
      "website": "https://acme.example.com",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-12-15T10:30:00Z",
      "user_role": "admin",
      "user_count": 45,
      "project_count": 12,
      "plan": {
        "name": "Business",
        "tier": "business"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "pages": 1
  }
}

Create Organization

Create a new organization.

POST /api/v1/organizations

Request Body

{
  "name": "TechStart Inc",
  "slug": "techstart",
  "description": "Innovation in AI and data analytics",
  "website": "https://techstart.example.com",
  "industry": "technology",
  "size": "11-50"
}

Response

{
  "id": "org_xyz789ghi012",
  "name": "TechStart Inc",
  "slug": "techstart",
  "description": "Innovation in AI and data analytics",
  "website": "https://techstart.example.com",
  "created_at": "2025-01-20T14:00:00Z",
  "owner": {
    "id": "user_123",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "plan": {
    "name": "Free",
    "tier": "free"
  }
}

Get Organization

Get details of a specific organization.

GET /api/v1/organizations/{organization_id}

Response

{
  "id": "org_abc123def456",
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "description": "Leading provider of innovative solutions",
  "logo_url": "https://assets.providence.io/orgs/acme-corp/logo.png",
  "website": "https://acme.example.com",
  "industry": "technology",
  "size": "51-200",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-12-15T10:30:00Z",
  "settings": {
    "features": {
      "sso_enabled": true,
      "audit_logs": true,
      "custom_roles": false,
      "data_residency": "us-east-1"
    },
    "security": {
      "two_factor_required": true,
      "session_timeout_minutes": 60,
      "ip_allowlist": ["192.168.1.0/24"]
    },
    "defaults": {
      "project_visibility": "private",
      "user_role": "member"
    }
  },
  "usage": {
    "users": {
      "count": 45,
      "limit": 100
    },
    "projects": {
      "count": 12,
      "limit": 50
    },
    "storage": {
      "used_bytes": 10737418240,
      "limit_bytes": 107374182400
    },
    "queries": {
      "this_month": 15420,
      "limit_monthly": 100000
    }
  },
  "plan": {
    "name": "Business",
    "tier": "business",
    "price_monthly": 499,
    "billing_cycle": "monthly",
    "next_billing_date": "2025-02-01T00:00:00Z"
  }
}

Update Organization

Update organization details.

PATCH /api/v1/organizations/{organization_id}

Request Body

{
  "name": "Acme Corp International",
  "description": "Global leader in innovative solutions",
  "website": "https://acme-intl.example.com",
  "logo_url": "https://assets.example.com/new-logo.png"
}

Delete Organization

Delete an organization (requires owner role).

DELETE /api/v1/organizations/{organization_id}

Request Body

{
  "confirmation": "DELETE_ORGANIZATION_ACME_CORP",
  "reason": "Company merger",
  "transfer_to": "org_transferTarget123"  // Optional: transfer data to another org
}

Team Management

List Teams

Get all teams in an organization.

GET /api/v1/organizations/{organization_id}/teams

Response

{
  "teams": [
    {
      "id": "team_abc123",
      "name": "Data Analytics",
      "slug": "data-analytics",
      "description": "Business intelligence and analytics team",
      "member_count": 8,
      "project_count": 3,
      "created_at": "2024-03-15T10:00:00Z",
      "permissions": [
        "projects.create",
        "projects.read",
        "projects.update",
        "datasets.manage"
      ]
    }
  ]
}

Create Team

Create a new team.

POST /api/v1/organizations/{organization_id}/teams

Request Body

{
  "name": "Engineering",
  "slug": "engineering",
  "description": "Product engineering team",
  "permissions": [
    "projects.create",
    "projects.read",
    "projects.update",
    "projects.delete",
    "datasets.manage",
    "queries.execute"
  ]
}

Get Team

Get team details including members.

GET /api/v1/organizations/{organization_id}/teams/{team_id}

Response

{
  "id": "team_abc123",
  "name": "Data Analytics",
  "slug": "data-analytics",
  "description": "Business intelligence and analytics team",
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-12-01T14:30:00Z",
  "permissions": [
    "projects.create",
    "projects.read",
    "projects.update",
    "datasets.manage"
  ],
  "members": [
    {
      "id": "user_456",
      "name": "Jane Smith",
      "email": "[email protected]",
      "role": "team_lead",
      "joined_at": "2024-03-15T10:00:00Z"
    },
    {
      "id": "user_789",
      "name": "Bob Johnson",
      "email": "[email protected]",
      "role": "member",
      "joined_at": "2024-04-01T09:00:00Z"
    }
  ],
  "projects": [
    {
      "id": "proj_123",
      "name": "Sales Analytics",
      "role": "admin"
    }
  ]
}

Add Team Member

Add a user to a team.

POST /api/v1/organizations/{organization_id}/teams/{team_id}/members

Request Body

{
  "user_id": "user_999",
  "role": "member"
}

Remove Team Member

Remove a user from a team.

DELETE /api/v1/organizations/{organization_id}/teams/{team_id}/members/{user_id}

User Management

List Organization Users

Get all users in an organization.

GET /api/v1/organizations/{organization_id}/users

Parameters

Name	Type	Location	Required	Description
page	integer	query	No	Page number (default: 1)
limit	integer	query	No	Items per page (default: 20)
search	string	query	No	Search by name or email
role	string	query	No	Filter by role
team_id	string	query	No	Filter by team membership
status	string	query	No	Filter by status: active, invited, disabled

Response

{
  "users": [
    {
      "id": "user_123",
      "name": "John Doe",
      "email": "[email protected]",
      "avatar_url": "https://avatars.providence.io/user_123.jpg",
      "role": "admin",
      "status": "active",
      "teams": [
        {
          "id": "team_abc123",
          "name": "Data Analytics",
          "role": "member"
        }
      ],
      "joined_at": "2024-01-15T10:00:00Z",
      "last_active_at": "2025-01-20T15:30:00Z",
      "two_factor_enabled": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

Invite User

Invite a new user to the organization.

POST /api/v1/organizations/{organization_id}/invitations

Request Body

{
  "email": "[email protected]",
  "name": "New User",
  "role": "member",
  "teams": ["team_abc123"],
  "message": "Welcome to our analytics platform!",
  "expires_in_days": 7
}

Response

{
  "invitation_id": "inv_xyz789",
  "email": "[email protected]",
  "status": "pending",
  "expires_at": "2025-01-27T14:00:00Z",
  "invitation_url": "https://app.providence.io/invite/inv_xyz789"
}

Update User Role

Change a user's organization role.

PATCH /api/v1/organizations/{organization_id}/users/{user_id}

Request Body

{
  "role": "admin"
}

Remove User

Remove a user from the organization.

DELETE /api/v1/organizations/{organization_id}/users/{user_id}

Organization Settings

Get Settings

Get organization settings.

GET /api/v1/organizations/{organization_id}/settings

Update Settings

Update organization settings.

PATCH /api/v1/organizations/{organization_id}/settings

Request Body

{
  "security": {
    "two_factor_required": true,
    "session_timeout_minutes": 30,
    "ip_allowlist": ["10.0.0.0/8", "192.168.0.0/16"]
  },
  "defaults": {
    "project_visibility": "private",
    "user_role": "member",
    "dataset_retention_days": 90
  },
  "notifications": {
    "email_digest": "weekly",
    "usage_alerts": true,
    "security_alerts": true
  }
}

API Keys

List API Keys

Get organization API keys.

GET /api/v1/organizations/{organization_id}/api-keys

Create API Key

Create a new API key.

POST /api/v1/organizations/{organization_id}/api-keys

Request Body

{
  "name": "Production API Key",
  "description": "Used by production data pipeline",
  "permissions": [
    "projects.read",
    "datasets.read",
    "queries.execute"
  ],
  "expires_at": "2025-12-31T23:59:59Z"
}

Response

{
  "id": "key_abc123",
  "name": "Production API Key",
  "key": "pvd_live_abcdef123456...",  // Only shown once
  "key_preview": "pvd_live_...3456",
  "created_at": "2025-01-20T14:00:00Z",
  "expires_at": "2025-12-31T23:59:59Z"
}

Revoke API Key

Revoke an API key.

DELETE /api/v1/organizations/{organization_id}/api-keys/{key_id}

Usage & Billing

Get Usage

Get detailed usage statistics.

GET /api/v1/organizations/{organization_id}/usage

Parameters

Name	Type	Location	Required	Description
period	string	query	No	Period: current_month, last_month, custom
start_date	string	query	No	Start date for custom period
end_date	string	query	No	End date for custom period
breakdown	string	query	No	Breakdown by: project, user, team

Response

{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "usage": {
    "queries": {
      "count": 15420,
      "limit": 100000,
      "percentage": 15.42
    },
    "storage": {
      "bytes": 10737418240,
      "limit_bytes": 107374182400,
      "percentage": 10.0,
      "breakdown": {
        "datasets": 8589934592,
        "query_results": 2147483648
      }
    },
    "compute": {
      "seconds": 3600,
      "limit_seconds": 36000,
      "percentage": 10.0
    },
    "users": {
      "active": 35,
      "total": 45,
      "limit": 100
    }
  },
  "cost": {
    "current": 125.50,
    "projected": 499.00,
    "currency": "USD"
  }
}

Get Billing Info

Get billing information and invoices.

GET /api/v1/organizations/{organization_id}/billing

Audit Logs

Get Audit Logs

Retrieve organization audit logs (requires admin role).

GET /api/v1/organizations/{organization_id}/audit-logs

Parameters

Name	Type	Location	Required	Description
page	integer	query	No	Page number
limit	integer	query	No	Items per page
actor_id	string	query	No	Filter by user ID
action	string	query	No	Filter by action type
resource_type	string	query	No	Filter by resource type
start_date	string	query	No	Start date filter
end_date	string	query	No	End date filter

Response

{
  "logs": [
    {
      "id": "log_123456",
      "timestamp": "2025-01-20T15:30:00Z",
      "actor": {
        "id": "user_123",
        "name": "John Doe",
        "email": "[email protected]"
      },
      "action": "user.invite",
      "resource": {
        "type": "user",
        "id": "user_999",
        "name": "[email protected]"
      },
      "details": {
        "role": "member",
        "teams": ["team_abc123"]
      },
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0..."
    }
  ]
}

Error Responses

403 Forbidden

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to perform this action",
    "details": {
      "required_role": "admin",
      "your_role": "member"
    }
  }
}

422 Unprocessable Entity

{
  "error": {
    "code": "PLAN_LIMIT_EXCEEDED",
    "message": "Your plan doesn't support this many users",
    "details": {
      "current_users": 100,
      "plan_limit": 100,
      "suggested_plan": "enterprise"
    }
  }
}

Webhooks

Organization events can trigger webhooks:

organization.created
organization.updated
organization.deleted
user.invited
user.joined
user.removed
team.created
team.updated
team.deleted

See the Webhooks documentation for details.

Best Practices

Least Privilege: Assign minimum required permissions
Team Structure: Organize users into logical teams
API Key Rotation: Regularly rotate API keys
Audit Logs: Monitor audit logs for security
Usage Monitoring: Track usage to avoid limits

Rate Limits

Organization operations: 100 per hour
User invitations: 50 per day
API key creation: 10 per day

See Rate Limiting for more details.

Organizations API

On this page