--- updatedAt: 2026-03-05T20:36:30.000Z agentTools: projectIndex: https://developers.hive.com/llms.txt --- # List groups Retrieve a paginated list of groups (teams) in the workspace. Supports filtering by `displayName` (team name). Pagination uses 1-based indexing as defined by the SCIM specification. # OpenAPI definition ````json { "openapi": "3.0.3", "info": { "title": "Hive SCIM 2.0 API", "version": "2.0", "description": "The Hive SCIM 2.0 API enables Identity Providers (IdPs) such as Okta, Azure AD, OneLogin, and JumpCloud to automatically provision and manage users and groups within a Hive workspace.\n\nSCIM (System for Cross-domain Identity Management) is an open standard defined in [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644) that automates user lifecycle management, including creating accounts, updating profiles, deactivating users, and managing group membership.\n\n## Authentication\n\nAll requests must include a Bearer token in the `Authorization` header. The token is a Hive API key.\n\n```\nAuthorization: Bearer \n```\n\n**Requirements:**\n- The API key owner must be a **system admin** in the target workspace.\n- API keys are generated in the Hive app under **My Settings > API Info**.\n\n### Generating an API Key\n\n1. Click your **user avatar** in the top-right corner of Hive.\n2. Select **My Settings**.\n3. In the left sidebar, click **API Info**.\n4. Click **Generate API Key** (or **Regenerate** if one already exists).\n5. Copy the API key and use it as the Bearer token for SCIM requests.\n\nThe same API key is used for both the Hive REST API and the SCIM API.\n\n## Finding Your Workspace ID\n\nThe `workspaceId` is required in the URL path for all SCIM endpoints. You can find it in several ways:\n\n- **From the URL**: When viewing your workspace in Hive, the workspace ID appears in the browser address bar: `https://app.hive.com/workspace/{workspaceId}`\n- **From the API Info page**: The workspace ID is displayed alongside your API key in **My Settings > API Info**.\n- **From Enterprise Security settings**: Navigate to **Workspace Settings > Enterprise Security > Authentication** to find a dedicated Workspace ID field with a copy button.\n\n## Content Type\n\nAll requests and responses use the `application/scim+json` content type as defined by the SCIM 2.0 specification.\n\n## Supported Identity Providers\n\nHive's SCIM API is compatible with any IdP that supports the SCIM 2.0 standard, including:\n- **Okta**\n- **Azure Active Directory (Entra ID)**\n- **OneLogin**\n- **JumpCloud**\n- **Ping Identity**\n- **Google Workspace** (via third-party SCIM bridges)\n\n## Important Notes\n\n- `DELETE /Users/{id}` does not permanently delete a user. It removes the user from the workspace (deactivation). The user can be re-provisioned later.\n- `externalId` is optional but recommended. It allows Hive to match users even if their email address changes in the IdP.\n- Group names are treated as unique per workspace. Creating a group with a name that already exists will update the existing group.\n- Only the `eq` filter operator is supported for `filter` query parameters.\n", "contact": { "name": "Hive Support", "url": "https://help.hive.com", "email": "support@hive.com" }, "x-readme": { "explorer-enabled": true } }, "servers": [ { "url": "https://scim.hive.com/v2/{workspaceId}", "description": "Hive SCIM 2.0 Production", "variables": { "workspaceId": { "description": "Your Hive workspace ID. Found in the browser URL bar or under My Settings > API Info.", "default": "YOUR_WORKSPACE_ID" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Groups", "description": "Manage workspace teams via the SCIM Groups resource. Each Hive team maps to a SCIM Group with a `displayName` and `members` list.\n\nGroups in Hive correspond to **teams**. Team membership is managed through group operations.\n" } ], "paths": { "/Groups": { "get": { "tags": [ "Groups" ], "summary": "List groups", "operationId": "listGroups", "description": "Retrieve a paginated list of groups (teams) in the workspace. Supports filtering by `displayName` (team name).\n\nPagination uses 1-based indexing as defined by the SCIM specification.\n", "parameters": [ { "name": "startIndex", "in": "query", "description": "1-based index of the first result to return. Defaults to 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "count", "in": "query", "description": "Maximum number of results to return per page. Defaults to 20, maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "filter", "in": "query", "description": "SCIM filter expression. Only the `eq` operator is supported.\n\nExample: `displayName eq \"Engineering\"`\n", "schema": { "type": "string" }, "example": "displayName eq \"Engineering\"" } ], "responses": { "200": { "description": "A paginated list of groups.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroupListResponse" }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 5, "startIndex": 1, "itemsPerPage": 5, "Resources": [ { "id": "team789", "displayName": "Engineering", "members": [ { "value": "abc123def456", "display": "Will Allhill" } ], "meta": { "resourceType": "Group" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Hive API key used as a Bearer token. Generate one in Hive under **My Settings > API Info**.\n\nThe API key owner must be a system admin in the target workspace.\n" } }, "schemas": { "ScimGroupMember": { "type": "object", "properties": { "value": { "type": "string", "description": "The Hive user ID of the group member.", "example": "abc123def456" }, "display": { "type": "string", "description": "The member's full name.", "example": "Will Allhill" } } }, "ScimGroup": { "type": "object", "properties": { "id": { "type": "string", "description": "The Hive team ID.", "example": "team789" }, "displayName": { "type": "string", "description": "The team name.", "example": "Engineering" }, "members": { "type": "array", "description": "Users who belong to this team.", "items": { "$ref": "#/components/schemas/ScimGroupMember" } }, "meta": { "type": "object", "properties": { "resourceType": { "type": "string", "enum": [ "Group" ], "example": "Group" } } } } }, "ScimGroupListResponse": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "totalResults": { "type": "integer", "description": "Total number of groups matching the query.", "example": 5 }, "startIndex": { "type": "integer", "description": "1-based index of the first result returned.", "example": 1 }, "itemsPerPage": { "type": "integer", "description": "Number of results returned in this page.", "example": 5 }, "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimGroup" } } } }, "ScimError": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:Error" ] }, "detail": { "type": "string", "description": "A human-readable error message.", "example": "Not authorized" }, "status": { "type": "string", "description": "The HTTP status code as a string.", "example": "401" } } } }, "responses": { "Unauthorized": { "description": "Authentication failed. The API key is missing, invalid, or the key owner is not a system admin in the target workspace.", "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" }, "example": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "Not authorized", "status": "401" } } } } } } } ````