Members

Organization members are users who have access to your Capgo organization. Each member has a specific role that determines their permissions within the organization. Managing members effectively is crucial for maintaining security and collaboration in your team.

Member Roles

Regular Roles

• read: Can view resources but cannot make changes
• upload: Can upload new bundles and view resources
• write: Can modify resources and upload bundles
• admin: Can manage organization settings and members
• super_admin: Has full control over the organization

Invite Roles

• invite_read: Pending invitation for read access
• invite_upload: Pending invitation for upload access
• invite_write: Pending invitation for write access
• invite_admin: Pending invitation for admin access
• invite_super_admin: Pending invitation for super admin access

Best Practices

1. Role Assignment: Follow the principle of least privilege when assigning roles
2. Regular Audits: Periodically review member access and remove unused accounts
3. Onboarding: Have a clear process for adding new members and assigning roles
4. Offboarding: Promptly remove access for members who leave the organization

Endpoints

POST

https://api.capgo.app/organization/members/

Add a new member to an organization or update an existing member’s role. Note that you can only invite users who already have a Capgo account - the email must correspond to an existing Capgo user.

Request Body

interface MemberCreate {
  orgId: string
  email: string
  role: "read" | "upload" | "write" | "admin" | "super_admin"
}

Example Request

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "email": "newmember@example.com",
    "role": "write"
  }' \
  https://api.capgo.app/organization/members/

Success Response

{
  "status": "OK",
  "data": {
    "uid": "user_789",
    "email": "newmember@example.com",
    "role": "invite_write",
    "image_url": null
  }
}

Notes:

• When adding a new member, they will receive an invitation email. Their role will be prefixed with “invite_” until they accept the invitation.
• The user must already have a Capgo account before they can be invited. If they don’t have an account, they should first create one at https://console.capgo.app/register/

GET

https://api.capgo.app/organization/members/

Retrieve all members of an organization.

Query Parameters

interface MemberQuery {
  orgId: string
}

Response Type

interface Member {
  uid: string;
  email: string;
  image_url: string;
  role: "invite_read" | "invite_upload" | "invite_write" | "invite_admin" | "invite_super_admin" | "read" | "upload" | "write" | "admin" | "super_admin";
}

Example Request

curl -H "authorization: your-api-key" \
  "https://api.capgo.app/organization/members/?orgId=org_123"

Example Response

{
  "data": [
    {
      "uid": "user_123",
      "email": "john@example.com",
      "image_url": "https://example.com/avatar.png",
      "role": "admin"
    },
    {
      "uid": "user_456",
      "email": "jane@example.com",
      "image_url": "https://example.com/avatar2.png",
      "role": "write"
    },
    {
      "uid": "user_789",
      "email": "bob@example.com",
      "image_url": null,
      "role": "invite_read"
    }
  ]
}

DELETE

https://api.capgo.app/organization/members/

Remove a member from an organization. This will immediately revoke their access.

Request Body

interface MemberDelete {
  orgId: string
  email: string
}

Example Request

curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "email": "user@example.com"
  }' \
  https://api.capgo.app/organization/members/

Success Response

{
  "status": "OK"
}

Error Handling

Common error scenarios and their responses:

// Member not found
{
  "error": "Member not found",
  "status": "KO"
}

// Invalid role
{
  "error": "Invalid role specified",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage members",
  "status": "KO"
}

// Cannot remove last admin
{
  "error": "Cannot remove the last admin from the organization",
  "status": "KO"
}

// Invalid email
{
  "error": "Invalid email format",
  "status": "KO"
}

// Member already exists
{
  "error": "Member already exists in organization",
  "status": "KO"
}

Common Use Cases

1. Team Expansion: Adding new team members with appropriate roles
2. Access Control: Managing member permissions as responsibilities change
3. Security Audit: Reviewing member list and roles periodically
4. Team Restructuring: Updating roles during organizational changes

Keep going from Members

If you are using Members to plan security and compliance, connect it with Encryption for the implementation detail in Encryption, Compliance for the implementation detail in Compliance, Capgo Security Scanner for the product workflow in Capgo Security Scanner, Capgo Security for the product workflow in Capgo Security, and Capgo Trust Center for the product workflow in Capgo Trust Center.