Members

Manage organization members via API

Organization members have access to apps, resources, and settings within an organization. Use this API to programmatically manage team access.

List Members

GET https://api.spice.ai/v1/members

Returns a list of members in the authenticated organization.

Required scope: members:read

Response

200: OK

{
  "members": [
    {
      "user_id": 1,
      "username": "alice",
      "roles": ["owner"],
      "is_owner": true,
      "created_at": "2024-01-01T00:00:00.000Z"
    },
    {
      "user_id": 2,
      "username": "bob",
      "roles": ["member"],
      "is_owner": false,
      "created_at": "2024-01-15T10:00:00.000Z"
    }
  ]
}

Response Fields:

Field	Type	Description
user_id	integer	User identifier
username	string	GitHub username
roles	string[]	Roles assigned to the member
is_owner	boolean	Whether the user is the organization owner
created_at	string	ISO 8601 timestamp when member was added

401: Unauthorized

403: Forbidden

Example

curl -H "Authorization: Bearer <token>" \
  https://api.spice.ai/v1/members

Python:

import requests

response = requests.get(
    "https://api.spice.ai/v1/members",
    headers={"Authorization": f"Bearer {token}"}
)

members = response.json()["members"]
for member in members:
    owner_badge = " (owner)" if member["is_owner"] else ""
    print(f"{member['username']}{owner_badge} - roles: {', '.join(member['roles'])}")

Add Member

POST https://api.spice.ai/v1/members

Adds a new member to the organization with specified roles.

Required scope: members:write

Request Body

{
  "username": "charlie",
  "roles": ["member"]
}

Request Fields:

Field	Type	Required	Description
username	string	Yes	GitHub username of the user to add
roles	string[]	No	Roles to assign (default: ["member"])

Response

201: Created

{
  "user_id": 3,
  "username": "charlie",
  "roles": ["member"],
  "created_at": "2024-01-20T15:00:00.000Z"
}

400: Bad Request

404: Not Found

409: Conflict

Examples

Add a member with default role:

curl -X POST https://api.spice.ai/v1/members \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "charlie"
  }'

Add a member with custom roles:

curl -X POST https://api.spice.ai/v1/members \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "david",
    "roles": ["member", "billing"]
  }'

Python:

import requests

response = requests.post(
    "https://api.spice.ai/v1/members",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json={
        "username": "eve",
        "roles": ["member"]
    }
)

if response.status_code == 201:
    member = response.json()
    print(f"Added {member['username']} to organization")
elif response.status_code == 404:
    print("User not found. User must sign in to Spice.ai first.")
elif response.status_code == 409:
    print("User is already a member")

Node.js:

const response = await fetch('https://api.spice.ai/v1/members', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'frank',
    roles: ['member']
  })
});

if (response.ok) {
  const member = await response.json();
  console.log(`Added ${member.username} to organization`);
} else if (response.status === 404) {
  console.log('User not found. User must sign in to Spice.ai first.');
} else if (response.status === 409) {
  console.log('User is already a member');
}

Remove Member

DELETE https://api.spice.ai/v1/members/{memberId}

Removes a member from the organization (soft delete). Member access is revoked immediately.

Required scope: members:delete

Path Parameters

Parameter	Type	Description
memberId	integer	The user ID of the member to remove

Response

204: No Content

Member removed successfully. No response body.

403: Forbidden

404: Not Found

Example

curl -X DELETE https://api.spice.ai/v1/members/3 \
  -H "Authorization: Bearer <token>"

Removing a member revokes their access to all apps and resources in the organization. This action cannot be undone (the member must be re-added).

Member Roles

Members can have one or more roles:

Role	Description
owner	Organization owner (cannot be removed, full access)
member	Standard member access to apps and resources
billing	Can manage billing and subscription
admin	Administrative access (planned)

Currently, all members have full access to organization resources. Fine-grained role-based access control is planned for future releases.

Prerequisites

Users must sign in to Spice.ai at least once before they can be added to an organization. If you try to add a user who hasn't signed in, you'll receive a 404 Not Found error.

User onboarding flow:

1. User signs in to spice.ai with GitHub

2. User's account is created

3. Organization admin adds user via API or portal

Bulk Operations

Add multiple members:

import requests

members_to_add = ["alice", "bob", "charlie"]

for username in members_to_add:
    response = requests.post(
        "https://api.spice.ai/v1/members",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        },
        json={"username": username, "roles": ["member"]}
    )

    if response.status_code == 201:
        print(f"✓ Added {username}")
    elif response.status_code == 404:
        print(f"✗ {username} not found (needs to sign in first)")
    elif response.status_code == 409:
        print(f"- {username} already a member")
    else:
        print(f"✗ Failed to add {username}: {response.json()}")

List all members with details:

import requests
from datetime import datetime

response = requests.get(
    "https://api.spice.ai/v1/members",
    headers={"Authorization": f"Bearer {token}"}
)

members = response.json()["members"]

print(f"Organization has {len(members)} members:\n")
for member in sorted(members, key=lambda m: m["created_at"]):
    created = datetime.fromisoformat(member["created_at"].replace("Z", "+00:00"))
    days_ago = (datetime.now(created.tzinfo) - created).days

    owner_badge = "👑" if member["is_owner"] else "  "
    roles_str = ", ".join(member["roles"])

    print(f"{owner_badge} {member['username']:20} {roles_str:20} (joined {days_ago} days ago)")

Best Practices

Access Management

1. Least Privilege - Assign minimal necessary roles to members

2. Regular Audits - Periodically review member list and remove inactive users

3. Onboarding - Ensure new team members sign in before adding them

4. Offboarding - Remove members immediately when they leave the team

Automation

# Sync team from GitHub organization
gh api orgs/my-org/members --jq '.[].login' | while read username; do
  curl -X POST https://api.spice.ai/v1/members \
    -H "Authorization: Bearer $SPICE_PAT" \
    -H "Content-Type: application/json" \
    -d "{\"username\": \"$username\", \"roles\": [\"member\"]}" \
    -s -o /dev/null -w "Added $username: %{http_code}\n"
done

Organization Structure

For teams with complex access requirements:

• Use separate organizations for different teams or projects

• Create service accounts for automation (using PATs)

• Document member roles and responsibilities

Limitations

• Members can only be added if they have a Spice.ai account (must sign in first)

• Organization owner cannot be removed or changed via API

• Role-based access control is currently limited (all members have full access)

• Personal organizations (matching username) cannot add/remove members

Troubleshooting

User Not Found (404)

The user doesn't have a Spice.ai account yet:

1. Ask the user to sign in to spice.ai with GitHub

2. Verify the username is correct (case-sensitive)

3. Try adding the member again after they sign in

User Already a Member (409)

The user is already in the organization:

• To update roles, remove and re-add the member (planned: PATCH endpoint)

• Use GET /v1/members to list current members

Cannot Remove Owner (403)

The organization owner cannot be removed:

• Transfer ownership through the portal first (if needed)

• Or create a new organization with a different owner

Terraform

Use the spiceai_member resource to manage members. See Terraform Provider for full documentation.

resource "spiceai_member" "team" {
  for_each = toset(["alice", "bob", "charlie"])

  username = each.key
  roles    = ["member"]
}

See also:

• Organizations - Manage organizations in the portal

• Apps API - Create apps for your team

• Personal Access Tokens - Create tokens for team members