Membership Management API

This document describes the auth-service membership routes currently registered in auth-service/backend/pkg/server/server.go.

Concepts

• Organizations and projects are identified by integer IDs from the governance service.
• Users are identified by the auth-service user UUID.
• Organization membership is managed by organization owners.
• Project membership is managed by project owners.
• RBAC metadata and permission checks are exposed under /api/v1/rbac.

Authentication

Membership routes use the combined-auth middleware (auth-service/backend/pkg/middleware/combined_auth.go), which accepts either:

• a bearer JWT from the configured IDP (or an enriched token issued by auth-service when using Keycloak/Entra token exchange), or
• an auth-service API key, supplied via Authorization: Bearer <api-key>.

Authorization: Bearer <token-or-api-key>

Dedicated API-key-only routes are exposed under /api/v1/service/* for service-to-service callers that don’t need user-context claims.

Organization Members

Add Member

POST /api/v1/organizations/{organizationId}/members

Requires organization-owner access.

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "roles": ["organization_owner"]
}

Remove Member

DELETE /api/v1/organizations/{organizationId}/members/{userId}

Requires organization-owner access.

Update Member Roles

PATCH /api/v1/organizations/{organizationId}/members/{userId}

Requires organization-owner access.

{
  "roles": ["organization_owner"]
}

List Organization Memberships

GET /api/v1/organizations/{organizationId}/memberships
GET /api/v1/organizations/{organizationId}/members/{userId}/memberships

Requires organization-owner or project-owner access within the organization.

Project Members

Project member routes are nested under the organization:

POST   /api/v1/organizations/{organizationId}/projects/{projectId}/members/{userId}
DELETE /api/v1/organizations/{organizationId}/projects/{projectId}/members/{userId}
PUT    /api/v1/organizations/{organizationId}/projects/{projectId}/members/{userId}

These routes require project-owner access.

Project-level roles:

• project_owner
• implementation_owner
• implementation_contributor
• audit_owner
• audit_contributor
• project_viewer

Organization-level role:

• organization_owner

RBAC Metadata

GET /api/v1/rbac/user/permissions
GET /api/v1/rbac/user/roles
GET /api/v1/rbac/metadata/roles
GET /api/v1/rbac/metadata/permissions
GET /api/v1/rbac/check/permission/{permission}
GET /api/v1/rbac/check/permission/{permission}/project/{projectId}

These routes use combined auth and support both JWTs and API keys where the middleware can resolve a user context.

Notes

• The active role and permission definitions live in auth-service/backend/pkg/rbac/roles.go and auth-service/backend/pkg/rbac/permissions.go.
• project_viewer is read-only project access.
• API response shapes are generated in Swagger from the handler annotations; use /swagger/ when the service is running with SWAGGER_ENABLED=true.