Organizations API

Manage organizations, members, invitations, roles, and audit logs.

Endpoints Summary

Organization Management

Method	Endpoint	Description
`GET`	`/api/orgs`	List your organizations
`POST`	`/api/orgs`	Create an organization
`GET`	`/api/orgs/:orgId`	Get organization details
`PUT`	`/api/orgs/:orgId`	Update organization
`DELETE`	`/api/orgs/:orgId`	Delete organization

Member Management

Method	Endpoint	Description
`GET`	`/api/orgs/:orgId/members`	List members
`PUT`	`/api/orgs/:orgId/members/:userId`	Update member role
`DELETE`	`/api/orgs/:orgId/members/:userId`	Remove member
`POST`	`/api/orgs/:orgId/members/:userId/move`	Move member to another org
`POST`	`/api/orgs/:orgId/transfer-ownership`	Transfer ownership
`POST`	`/api/orgs/:orgId/leave`	Leave organization

Invitations

Method	Endpoint	Description
`POST`	`/api/orgs/:orgId/invitations/email`	Invite by email
`POST`	`/api/orgs/:orgId/invitations/link`	Generate invite link
`GET`	`/api/orgs/:orgId/invitations`	List invitations
`DELETE`	`/api/orgs/:orgId/invitations/:id`	Revoke invitation

Audit Logs

Method	Endpoint	Description
`GET`	`/api/orgs/:orgId/audit-logs`	List audit logs
`GET`	`/api/orgs/:orgId/audit-logs/export`	Export audit logs (CSV)

Custom Roles Team+

Method	Endpoint	Description
`GET`	`/api/orgs/:orgId/roles`	List custom roles
`POST`	`/api/orgs/:orgId/roles`	Create a custom role
`PATCH`	`/api/orgs/:orgId/roles/:roleId`	Update a custom role
`DELETE`	`/api/orgs/:orgId/roles/:roleId`	Delete a custom role

Authentication

All endpoints require a Bearer token in the Authorization header.

Authorization: Bearer <your-api-token>

List Organizations

GET /api/orgs

Returns all organizations you belong to.

Example:

bash

curl -X GET "https://api.controlinfra.com/api/orgs" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "organizations": [
    {
      "_id": "663e1a2b3c4d5e6f7a8b9c0d",
      "name": "Acme Corp",
      "role": "owner",
      "memberCount": 8,
      "plan": "team",
      "createdAt": "2024-06-01T00:00:00Z"
    }
  ]
}

Create an Organization

POST /api/orgs

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Organization name

Example:

bash

curl -X POST "https://api.controlinfra.com/api/orgs" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp"
  }'

Response: 201 Created

json

{
  "_id": "663e1a2b3c4d5e6f7a8b9c0d",
  "name": "Acme Corp",
  "role": "owner",
  "plan": "free",
  "createdAt": "2025-01-15T10:00:00Z"
}

Get Organization Details

GET /api/orgs/:orgId

Example:

bash

curl -X GET "https://api.controlinfra.com/api/orgs/663e1a2b3c4d5e6f7a8b9c0d" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Organization

PUT /api/orgs/:orgId

Requires Owner or Admin role.

Request Body:

Field	Type	Description
`name`	string	Organization name

Example:

bash

curl -X PUT "https://api.controlinfra.com/api/orgs/663e1a2b3c4d5e6f7a8b9c0d" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation"
  }'

Delete Organization

DELETE /api/orgs/:orgId

Requires Owner role. Permanently deletes the organization and all associated data.

DANGER

This action is irreversible. All repositories, scans, drifts, and settings are permanently deleted.

Example:

bash

curl -X DELETE "https://api.controlinfra.com/api/orgs/663e1a2b3c4d5e6f7a8b9c0d" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

List Members

GET /api/orgs/:orgId/members

Example:

bash

curl -X GET "https://api.controlinfra.com/api/orgs/663e1a2b.../members" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "members": [
    {
      "userId": "660a1b2c...",
      "username": "johndoe",
      "email": "john@acme.com",
      "role": "owner",
      "joinedAt": "2024-06-01T00:00:00Z"
    },
    {
      "userId": "660a1b2d...",
      "username": "janedoe",
      "email": "jane@acme.com",
      "role": "admin",
      "joinedAt": "2024-07-15T00:00:00Z"
    }
  ]
}

Update Member Role

PUT /api/orgs/:orgId/members/:userId

Requires Owner or Admin role.

Request Body:

Field	Type	Required	Description
`role`	string	Yes	New role: `admin`, `member`, `viewer`, or a custom role ID

Example:

bash

curl -X PUT "https://api.controlinfra.com/api/orgs/663e1a2b.../members/660a1b2d..." \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

Remove Member

DELETE /api/orgs/:orgId/members/:userId

Requires Owner or Admin role. Cannot remove the owner.

Example:

bash

curl -X DELETE "https://api.controlinfra.com/api/orgs/663e1a2b.../members/660a1b2d..." \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

Move Member

POST /api/orgs/:orgId/members/:userId/move

Move a member from this organization to another. Requires Owner or Admin role in both organizations.

Request Body:

Field	Type	Required	Description
`targetOrgId`	string	Yes	Target organization ID
`role`	string	No	Role in the target org (default: `member`)

Example:

bash

curl -X POST "https://api.controlinfra.com/api/orgs/663e1a2b.../members/660a1b2d.../move" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetOrgId": "663e1a2c...",
    "role": "member"
  }'

Transfer Ownership

POST /api/orgs/:orgId/transfer-ownership

Requires Owner role.

Request Body:

Field	Type	Required	Description
`newOwnerId`	string	Yes	User ID of the new owner (must be a current member)

Example:

bash

curl -X POST "https://api.controlinfra.com/api/orgs/663e1a2b.../transfer-ownership" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "newOwnerId": "660a1b2d..."
  }'

Leave Organization

POST /api/orgs/:orgId/leave

Leave the organization. Owners must transfer ownership before leaving.

Example:

bash

curl -X POST "https://api.controlinfra.com/api/orgs/663e1a2b.../leave" \
  -H "Authorization: Bearer YOUR_TOKEN"

Invite by Email

POST /api/orgs/:orgId/invitations/email

Request Body:

Field	Type	Required	Description
`email`	string	Yes	Email address
`role`	string	No	Role to assign (default: `member`)

Example:

bash

curl -X POST "https://api.controlinfra.com/api/orgs/663e1a2b.../invitations/email" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@acme.com",
    "role": "member"
  }'

Response: 201 Created

json

{
  "_id": "667a1b2c...",
  "email": "newuser@acme.com",
  "role": "member",
  "status": "pending",
  "expiresAt": "2025-01-22T10:00:00Z"
}

Generate Invite Link

POST /api/orgs/:orgId/invitations/link

Request Body:

Field	Type	Required	Description
`role`	string	No	Default role for users joining via link (default: `member`)

Example:

bash

curl -X POST "https://api.controlinfra.com/api/orgs/663e1a2b.../invitations/link" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer"
  }'

Response: 201 Created

json

{
  "_id": "667a1b2c...",
  "link": "https://console.controlinfra.com/join/abc123def456",
  "role": "viewer",
  "expiresAt": "2025-01-22T10:00:00Z"
}

List Invitations

GET /api/orgs/:orgId/invitations

Example:

bash

curl -X GET "https://api.controlinfra.com/api/orgs/663e1a2b.../invitations" \
  -H "Authorization: Bearer YOUR_TOKEN"

Revoke Invitation

DELETE /api/orgs/:orgId/invitations/:id

Example:

bash

curl -X DELETE "https://api.controlinfra.com/api/orgs/663e1a2b.../invitations/667a1b2c..." \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

List Audit Logs

GET /api/orgs/:orgId/audit-logs

Query Parameters:

Parameter	Type	Description
`action`	string	Filter by action type
`actorId`	string	Filter by actor user ID
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50)

Example:

bash

curl -X GET "https://api.controlinfra.com/api/orgs/663e1a2b.../audit-logs?action=member.invited&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "logs": [
    {
      "_id": "668a1b2c...",
      "action": "member.invited",
      "actor": {
        "userId": "660a1b2c...",
        "username": "johndoe"
      },
      "target": {
        "email": "newuser@acme.com"
      },
      "metadata": {
        "role": "member"
      },
      "ip": "203.0.113.42",
      "timestamp": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 156,
  "page": 1,
  "pages": 4
}

Export Audit Logs Team+

GET /api/orgs/:orgId/audit-logs/export

Returns audit logs as a CSV file download.

Query Parameters: Same as List Audit Logs.

Example:

bash

curl -X GET "https://api.controlinfra.com/api/orgs/663e1a2b.../audit-logs/export?from=2025-01-01" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o audit-logs.csv

List Custom Roles Team+

GET /api/orgs/:orgId/roles

Example:

bash

curl -X GET "https://api.controlinfra.com/api/orgs/663e1a2b.../roles" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "roles": [
    {
      "_id": "669a1b2c...",
      "name": "DevOps Lead",
      "description": "Full access to scans and guardrails, read-only members",
      "permissions": [
        "repositories:read",
        "repositories:write",
        "scans:read",
        "scans:write",
        "guardrails:read",
        "guardrails:write",
        "members:read"
      ],
      "memberCount": 3,
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Create a Custom Role Team+

POST /api/orgs/:orgId/roles

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Role name
`description`	string	No	Role description
`permissions`	string[]	Yes	Array of permission slugs

Available Permissions:

Permission	Description
`repositories:read`	View repositories
`repositories:write`	Create, edit, delete repositories
`scans:read`	View scan results
`scans:write`	Trigger and configure scans
`drifts:read`	View drift reports
`drifts:write`	Resolve, ignore drifts
`guardrails:read`	View guardrails
`guardrails:write`	Create, edit, deploy guardrails
`members:read`	View member list
`members:write`	Invite, edit roles, remove members
`settings:read`	View organization settings
`settings:write`	Edit organization settings
`billing:read`	View billing information
`billing:write`	Manage subscription
`audit:read`	View audit logs

Example:

bash

curl -X POST "https://api.controlinfra.com/api/orgs/663e1a2b.../roles" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DevOps Lead",
    "description": "Full access to scans and guardrails, read-only members",
    "permissions": [
      "repositories:read",
      "repositories:write",
      "scans:read",
      "scans:write",
      "guardrails:read",
      "guardrails:write",
      "members:read"
    ]
  }'

Response: 201 Created

Update a Custom Role Team+

PATCH /api/orgs/:orgId/roles/:roleId

Example:

bash

curl -X PATCH "https://api.controlinfra.com/api/orgs/663e1a2b.../roles/669a1b2c..." \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      "repositories:read",
      "repositories:write",
      "scans:read",
      "scans:write",
      "guardrails:read",
      "guardrails:write",
      "members:read",
      "members:write"
    ]
  }'

Delete a Custom Role Team+

DELETE /api/orgs/:orgId/roles/:roleId

Members with this role are reassigned to the built-in Member role.

Example:

bash

curl -X DELETE "https://api.controlinfra.com/api/orgs/663e1a2b.../roles/669a1b2c..." \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

Organizations API ​

Endpoints Summary ​

Organization Management ​

Member Management ​

Invitations ​

Audit Logs ​

Custom Roles Team+ ​

Authentication ​

List Organizations ​

Create an Organization ​

Get Organization Details ​

Update Organization ​

Delete Organization ​

List Members ​

Update Member Role ​

Remove Member ​

Move Member ​

Transfer Ownership ​

Leave Organization ​

Invite by Email ​

Generate Invite Link ​

List Invitations ​

Revoke Invitation ​

List Audit Logs ​

Export Audit Logs Team+ ​

List Custom Roles Team+ ​

Create a Custom Role Team+ ​

Update a Custom Role Team+ ​

Delete a Custom Role Team+ ​

Organizations API

Endpoints Summary

Organization Management

Member Management

Invitations

Audit Logs

Custom Roles Team+

Authentication

List Organizations

Create an Organization

Get Organization Details

Update Organization

Delete Organization

List Members

Update Member Role

Remove Member

Move Member

Transfer Ownership

Leave Organization

Invite by Email

Generate Invite Link

List Invitations

Revoke Invitation

List Audit Logs

Export Audit Logs Team+

List Custom Roles Team+

Create a Custom Role Team+

Update a Custom Role Team+

Delete a Custom Role Team+