Members API

The Members API provides read access to your workspace's team directory. Use it to audit membership, sync user lists with external systems, or display team rosters in your own applications.

The Member Object

Attributes

Attribute	Type	Description
`id`	string	Membership record ID
`user_id`	string	Internal user identifier
`name`	string	Display name (falls back to email if not set)
`email`	string	Email address
`avatar_url`	string	Avatar image URL (optional)
`role`	string	Role in the workspace: `owner`, `admin`, `member`, `viewer`
`status`	string	Membership status (e.g., `active`)
`joined_at`	string	ISO 8601 timestamp when the member joined

Example Object

{
  "id": "mem_abc123",
  "user_id": "usr_xyz789",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "avatar_url": "https://img.clerk.com/...",
  "role": "admin",
  "status": "active",
  "joined_at": "2024-01-15T09:00:00Z"
}

List Members

Retrieve all members of your workspace, sorted by role then join date.

Endpoint

GET /api/v1/members

Required Scope

seal:members:read

Query Parameters

Parameter	Type	Description
`role`	string	Filter by role: `owner`, `admin`, `member`, or `viewer`

TypeScript Example

const response = await fetch("https://seal.convex.site/api/v1/members", {
  headers: {
    Authorization: "Bearer ak_your_api_key_here",
  },
});

const { members } = await response.json();

cURL Example

curl -X GET "https://seal.convex.site/api/v1/members?role=admin" \
  -H "Authorization: Bearer ak_your_api_key_here"

Response

{
  "members": [
    {
      "id": "mem_owner1",
      "user_id": "usr_abc",
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "role": "owner",
      "status": "active",
      "joined_at": "2023-06-01T10:00:00Z"
    },
    {
      "id": "mem_admin1",
      "user_id": "usr_def",
      "name": "Bob Williams",
      "email": "bob@example.com",
      "role": "admin",
      "status": "active",
      "joined_at": "2023-08-15T14:30:00Z"
    }
  ]
}

Get Member

Retrieve a single workspace member by membership ID.

Endpoint

GET /api/v1/members/get?id={id}

Required Scope

seal:members:read

Query Parameters

Parameter	Type	Description
`id`	string	Required. Membership ID

TypeScript Example

const response = await fetch(
  "https://seal.convex.site/api/v1/members/get?id=mem_abc123",
  {
    headers: {
      Authorization: "Bearer ak_your_api_key_here",
    },
  },
);

const member = await response.json();

cURL Example

curl -X GET "https://seal.convex.site/api/v1/members/get?id=mem_abc123" \
  -H "Authorization: Bearer ak_your_api_key_here"

Response

{
  "id": "mem_abc123",
  "user_id": "usr_xyz789",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "avatar_url": "https://img.clerk.com/...",
  "role": "admin",
  "status": "active",
  "joined_at": "2024-01-15T09:00:00Z"
}

Note: System-level members used for internal automation are excluded from all API responses.

Member Roles

Role	Description
`owner`	Full administrative access, including billing
`admin`	Can manage documents, members, and most settings
`member`	Can create and manage their own documents
`viewer`	Read-only access to documents shared with them

Next Steps

Settings API - Read and update workspace configuration
Audit Log API - View all workspace activity
Documents API - Manage documents

Members API

On this page