Organizations API
Manage organizations, members, and org-scoped resources.
Organization endpoints require user authentication via Clerk. API keys cannot access organization management endpoints.
List Organizations
Returns organizations the authenticated user belongs to.
GET /v1/orgs
Authorization: Bearer {clerk_session_token}Response
{
"organizations": [
{
"id": "org_abc123def456",
"name": "Acme Corporation",
"slug": "acme-corp",
"role": "owner",
"member_count": 12,
"created_at": "2025-01-15T08:00:00Z"
},
{
"id": "org_xyz789ghi012",
"name": "Security Team",
"slug": "security-team",
"role": "member",
"member_count": 5,
"created_at": "2025-06-20T14:30:00Z"
}
]
}Role Values
| Role | Description |
|---|---|
owner | Full access including org deletion |
admin | Manage members, settings, API keys |
member | View scans, submit feedback |
Get Organization
Returns details for a specific organization.
GET /v1/orgs/{org_id}
Authorization: Bearer {clerk_session_token}Path Parameters
| Parameter | Type | Description |
|---|---|---|
org_id | string | Organization ID |
Response
{
"id": "org_abc123def456",
"name": "Acme Corporation",
"slug": "acme-corp",
"member_count": 12,
"settings": {
"default_policy": "strict",
"require_justification": true,
"baseline_auto_update": false
},
"created_at": "2025-01-15T08:00:00Z",
"updated_at": "2025-12-01T10:00:00Z"
}Errors
| Status | Code | Description |
|---|---|---|
| 403 | org_access_denied | User is not a member of this organization |
| 404 | org_not_found | Organization does not exist |
List Organization Members
Returns all members of an organization.
GET /v1/orgs/{org_id}/members
Authorization: Bearer {clerk_session_token}Requires Admin or Owner role in the organization.
Response
{
"members": [
{
"user_id": "user_abc123",
"email": "alice@acme.com",
"name": "Alice Smith",
"avatar_url": "https://img.clerk.com/...",
"role": "owner",
"joined_at": "2025-01-15T08:00:00Z"
},
{
"user_id": "user_def456",
"email": "bob@acme.com",
"name": "Bob Johnson",
"avatar_url": "https://img.clerk.com/...",
"role": "admin",
"joined_at": "2025-03-20T09:30:00Z"
},
{
"user_id": "user_ghi789",
"email": "charlie@acme.com",
"name": "Charlie Brown",
"avatar_url": null,
"role": "member",
"joined_at": "2025-06-15T14:00:00Z"
}
],
"total": 3
}Get Organization Stats
Returns aggregated scan statistics for an organization.
GET /v1/orgs/{org_id}/stats
Authorization: Bearer {clerk_session_token}Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
since | ISO 8601 | 30 days ago | Start of date range |
until | ISO 8601 | now | End of date range |
Response
{
"total_scans": 1247,
"unique_agents": 23,
"findings": {
"total": 892,
"by_severity": {
"critical": 12,
"high": 67,
"medium": 312,
"low": 501
},
"by_category": {
"security": 245,
"governance": 312,
"reliability": 335
}
},
"risk_score": {
"average": 42,
"trend": -5.2,
"trend_direction": "improving"
},
"scan_frequency": {
"daily_average": 8.3,
"weekly_total": 58
},
"last_scan_at": "2025-12-28T09:45:00Z"
}Get Organization Scans
Returns scan history for an organization.
GET /v1/orgs/{org_id}/scans
Authorization: Bearer {clerk_session_token}Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Max results (1-100) |
offset | integer | 0 | Pagination offset |
status | string | all | Filter: completed, failed, pending |
agent_id | string | - | Filter by agent |
since | ISO 8601 | - | Scans after this date |
Response
{
"scans": [
{
"id": "scan_abc123",
"agent_name": "customer-service-agent",
"status": "completed",
"finding_count": 5,
"risk_score": 35,
"created_at": "2025-12-28T09:45:00Z",
"completed_at": "2025-12-28T09:45:12Z"
}
],
"total": 1247,
"has_more": true
}Get Organization API Keys
Returns API keys created for an organization.
GET /v1/orgs/{org_id}/api-keys
Authorization: Bearer {clerk_session_token}Requires Admin or Owner role in the organization.
Response
{
"api_keys": [
{
"id": "key_abc123",
"name": "CI/CD Pipeline - Production",
"key_prefix": "ink_org_abc",
"scopes": ["scan:create", "scan:read"],
"last_used_at": "2025-12-28T08:00:00Z",
"created_at": "2025-06-01T10:00:00Z",
"created_by": {
"id": "user_xyz789",
"email": "alice@acme.com"
}
}
],
"total": 3
}Create Organization API Key
Creates a new API key scoped to an organization.
POST /v1/orgs/{org_id}/api-keys
Authorization: Bearer {clerk_session_token}
Content-Type: application/jsonRequires Admin or Owner role in the organization.
Request Body
{
"name": "CI/CD Pipeline - Staging",
"scopes": ["scan:create", "scan:read"]
}Available Scopes
| Scope | Description |
|---|---|
scan:create | Create new scans |
scan:read | Read scan results |
feedback:write | Submit calibration feedback |
Response
{
"id": "key_def456",
"name": "CI/CD Pipeline - Staging",
"key": "ink_org_Abc123Def456Ghi789...",
"key_prefix": "ink_org_Abc",
"scopes": ["scan:create", "scan:read"],
"created_at": "2025-12-28T10:00:00Z"
}The full API key is only returned once at creation time. Store it securely.
Get Organization Audit Logs
Returns audit log entries for an organization.
GET /v1/orgs/{org_id}/audit-logs
Authorization: Bearer {clerk_session_token}Requires Admin or Owner role in the organization.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
event_types | string | Comma-separated event types |
actor_id | string | Filter by actor |
since | ISO 8601 | Events after this time |
until | ISO 8601 | Events before this time |
limit | integer | Max results (default: 100) |
Response
{
"audit_logs": [
{
"id": "log_abc123",
"event_type": "api_key.created",
"actor": {
"id": "user_xyz789",
"email": "alice@acme.com",
"type": "user"
},
"resource_type": "api_key",
"resource_id": "key_def456",
"action": "create",
"metadata": {
"key_name": "CI/CD Pipeline",
"scopes": ["scan:create"]
},
"ip_address": "203.0.113.42",
"created_at": "2025-12-28T10:00:00Z"
}
],
"total": 1547,
"has_more": true
}Event Types
| Category | Events |
|---|---|
| API Keys | api_key.created, api_key.revoked, api_key.used |
| Scans | scan.started, scan.completed, scan.failed |
| Members | org.member.added, org.member.removed, org.member.role_changed |
| Suppressions | suppression.created, suppression.revoked |
| Feedback | feedback.added |
Related
- Suppressions API - Manage finding suppressions
- Scan API - Scan operations
- Organizations Guide - Multi-org setup guide
Last updated on