# Teams API Reference

The Teams API lets you create and delete teams, manage team membership, and retrieve team policy assignments. In the API, teams are referred to as `groups`. All endpoints are under the `/rbac/` base path and require a Service Account token with Admin role.

Replace `<your-instance>` with your Kloudfuse hostname and `<sa-token>` with a valid Service Account token.

Team names containing spaces or special characters must be URL-encoded in path segments (e.g. `ops team` becomes `ops%20team`). Email addresses must also be URL-encoded (e.g. `alice@example.com` becomes `alice%40example.com`).

For the Policies API, see [Policies API Reference](https://docs.kloudfuse.com/platform/4.1.0/reference/api/policies/).

## List Teams

Returns all teams in the system.

```bash
curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/rbac/groups"
```

Response

```json
{
  "groups": [
    {
      "name": "ops-team",
      "email": "",
      "member_count": 4,
      "local_grafana_id": 2
    },
    {
      "name": "platform-team",
      "email": "",
      "member_count": 2,
      "local_grafana_id": 3
    }
  ],
  "total": 2
}
```

## Get a Team

Returns details for a single team.

```bash
curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/rbac/groups/ops-team"
```

Response

```json
{
  "name": "ops-team",
  "email": "",
  "member_count": 4,
  "local_grafana_id": 2
}
```

## Create a Team

Creates a new team. The name must be unique across all teams.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/rbac/groups" \
     -d '{"name": "ops-team"}'
```

Response

```json
{
  "name": "ops-team",
  "email": "",
  "member_count": 0,
  "local_grafana_id": 8
}
```

## Delete a Team

Deletes a team and removes all its members and policy assignments. Returns `204 No Content` with an empty response body.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -X DELETE "https://<your-instance>/rbac/groups/ops-team"
```

## List Team Members

Returns all users currently in the team.

```bash
curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/rbac/groups/ops-team/users"
```

Response

```json
{
  "members": [
    {
      "email": "alice@example.com",
      "name": "Alice",
      "login": "alice@example.com",
      "role": "Member"
    },
    {
      "email": "bob@example.com",
      "name": "Bob",
      "login": "bob@example.com",
      "role": "Admin"
    }
  ]
}
```

Member `role` values:

| Value   | Effect                                                                 |
|---------|------------------------------------------------------------------------|
| `Member`| Standard team member. Inherits the team’s folder and policy assignments.|
| `Admin` | Can manage the team’s membership and settings, in addition to inheriting its assignments.

## Add a User to a Team

Adds a user to a team, or updates their team role if they are already a member.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X PUT "https://<your-instance>/rbac/groups/ops-team/users/alice%40example.com" \
     -d '{"role": "Member"}'
```

Response

```json
{
  "message": "User added to group successfully"
}
```

## Remove a User from a Team

Removes a user from a team. The user account itself is not deleted.

```bash
curl -H "Authorization: Bearer <sa-token>" \
     -X DELETE "https://<your-instance>/rbac/groups/ops-team/users/alice%40example.com"
```

Response

```json
{
  "message": "User removed from group successfully"
}
```

## Get Team Policies

Returns all policies directly assigned to a team.

```bash
curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/rbac/groups/ops-team/policies"
```

Response

```json
{
  "policies": [
    {
      "name": "Production Logs",
      "scope": {
        "type": "custom",
        "filters": [
          { "key": "kf_stream", "op": "=~", "value": "logs" },
          { "key": "env", "op": "=", "value": "production" }
        ]
      }
    }
  ]
}
```

## Get Team Effective Policies

Returns all policies assigned to the team and the resolved per-stream access after combining all policies with OR logic.

```bash
curl -H "Authorization: Bearer <sa-token>" \
  "https://<your-instance>/rbac/groups/ops-team/effective-policies"
```

Response

```json
{
  "name": "ops-team",
  "entity_type": "group",
  "policies": [
    {
      "name": "Production Logs",
      "scope": {
        "type": "custom",
        "filters": [
          { "key": "kf_stream", "op": "=~", "value": "logs" },
          { "key": "env", "op": "=", "value": "production" }
        ]
      }
    }
  ],
  "scopes": {
    "logs":    [{ "type": "custom", "filters": [{ "key": "env", "op": "=", "value": "production" }], "policy_name": "Production Logs" }],
    "metrics": [{ "type": "none", "policy_name": "default-deny-policy" }],
    "events":  [{ "type": "none", "policy_name": "default-deny-policy" }],
    "apm":     [{ "type": "none", "policy_name": "default-deny-policy" }],
    "rum":     [{ "type": "none", "policy_name": "default-deny-policy" }]
  },
  "direct_policy_count": 1,
  "total_policy_count": 1
}
```

## Error Codes

| HTTP Status | Meaning                                                              |
|-------------|----------------------------------------------------------------------|
| `200`      | Success.                                                          |
| `201`      | Team created.                                                     |
| `204`      | Delete succeeded (empty response body).                          |
| `400`      | Bad request — missing required field or referenced user does not exist. |
| `401`      | Missing or invalid `Authorization` header.                      |
| `403`      | Insufficient permissions.                                       |
| `404`      | Team or member not found.                                       |
| `409`      | Conflict — a team with that name already exists.               |