Guru User Management API Guide

Auth method: HTTP Basic Auth (email:api_token, Base64-encoded)

Setup steps

1. Log in to Guru and navigate to Settings > API Access.
2. Generate a personal API token.
3. Encode your Guru account email and API token as Base64 in the format email:api_token.
4. Pass the encoded value in the Authorization header: 'Authorization: Basic '.

List team members

• Method: GET
• URL: https://api.getguru.com/api/v1/members
• Watch out for: Returns all members including PENDING. Paginate using nextPage token if team is large.

Request example

GET /api/v1/members
Authorization: Basic <base64>

Response example

[
  {
    "id": "uuid-1234",
    "user": {"email": "alice@example.com", "firstName": "Alice"},
    "role": "AUTHOR",
    "status": "ACTIVE"
  }
]

Get a single team member

• Method: GET
• URL: https://api.getguru.com/api/v1/members/{memberId}
• Watch out for: memberId is the Guru member UUID, not the user's email.

Request example

GET /api/v1/members/uuid-1234
Authorization: Basic <base64>

Response example

{
  "id": "uuid-1234",
  "user": {"email": "alice@example.com"},
  "role": "AUTHOR",
  "status": "ACTIVE"
}

Invite a member (add user)

• Method: POST
• URL: https://api.getguru.com/api/v1/members/invite
• Watch out for: Invited users receive an email invite; status is PENDING until accepted. Seats must be available.

Request example

POST /api/v1/members/invite
Content-Type: application/json

{"emails": ["bob@example.com"], "role": "MEMBER"}

Response example

[
  {
    "id": "uuid-5678",
    "user": {"email": "bob@example.com"},
    "status": "PENDING"
  }
]

Update member role

• Method: PUT
• URL: https://api.getguru.com/api/v1/members/{memberId}
• Watch out for: Only role is updatable via this endpoint. Profile fields (name, email) are not writable.

Request example

PUT /api/v1/members/uuid-1234
Content-Type: application/json

{"role": "ADMIN"}

Response example

{
  "id": "uuid-1234",
  "role": "ADMIN",
  "status": "ACTIVE"
}

Remove a member

• Method: DELETE
• URL: https://api.getguru.com/api/v1/members/{memberId}
• Watch out for: Deactivates the member from the team. Does not delete the Guru user account globally.

Request example

DELETE /api/v1/members/uuid-1234
Authorization: Basic <base64>

Response example

HTTP 204 No Content

List groups

• Method: GET
• URL: https://api.getguru.com/api/v1/groups
• Watch out for: Groups control collection access. Membership changes require separate group-member endpoints.

Request example

GET /api/v1/groups
Authorization: Basic <base64>

Response example

[
  {"id": "grp-uuid", "name": "Engineering", "numberOfMembers": 12}
]

Add member to group

• Method: POST
• URL: https://api.getguru.com/api/v1/groups/{groupId}/members
• Watch out for: User must already be a team member before being added to a group.

Request example

POST /api/v1/groups/grp-uuid/members
Content-Type: application/json

{"email": "alice@example.com"}

Response example

HTTP 200 OK
{"id": "grp-uuid", "name": "Engineering"}

Remove member from group

• Method: DELETE
• URL: https://api.getguru.com/api/v1/groups/{groupId}/members/{memberId}
• Watch out for: Removing from a group revokes collection access granted via that group.

Request example

DELETE /api/v1/groups/grp-uuid/members/uuid-1234
Authorization: Basic <base64>

Response example

HTTP 204 No Content

• Rate limits: Guru enforces rate limits on API requests. Specific numeric limits are not publicly documented in official sources.
• Rate-limit headers: Unknown
• Retry-After header: Unknown
• Rate-limit notes: Official documentation does not publish specific rate limit thresholds. Contact Guru support for enterprise rate limit details.
• Pagination method: token
• Default page size: 50
• Max page size: 100
• Pagination pointer: nextPage

• Webhooks available: No
• Webhook notes: Guru does not publicly document outbound webhooks for user lifecycle events (invite, deactivate, role change) in official developer documentation as of the research date.
• Alternative event strategy: Use SCIM provisioning for automated user lifecycle management, or poll the /members endpoint for changes.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.getguru.com/scim/v2

• Supported operations: Create user (POST /Users), Read user (GET /Users/{id}), List users (GET /Users), Update user (PUT /Users/{id}), Deactivate user (PATCH /Users/{id} with active=false), Create group (POST /Groups), Read group (GET /Groups/{id}), List groups (GET /Groups), Update group membership (PATCH /Groups/{id}), Delete group (DELETE /Groups/{id})

Limitations:

• Requires Enterprise plan.
• SSO (SAML) must be configured and active before enabling SCIM.
• Supported IdPs: Okta, Azure AD (Entra ID), OneLogin.
• SCIM token is generated in Guru Settings > SCIM Provisioning; it is a bearer token separate from the REST API token.
• Deprovisioning sets user to inactive; it does not permanently delete the account.
• Group push maps to Guru Groups; collection access is controlled separately.

Three primary automation scenarios are supported by the Guru API, each with distinct caveats.

SCIM provisioning (Enterprise): Assign a user to the Guru SCIM app in Okta or Azure AD (Entra ID). The IdP sends POST /scim/v2/Users; Guru creates the member as ACTIVE, bypassing the email invite flow entirely. Group push via PATCH /scim/v2/Groups/{id} maps to Guru Groups and controls Collection access. SSO must be active before this flow will function.

REST API invite + group assignment: POST /api/v1/members/invite sends an email invite; the user status is PENDING until accepted. Group membership via POST /api/v1/groups/{groupId}/members cannot be set until the user's status transitions to ACTIVE - polling GET /api/v1/members is required to detect that transition.

Offboarding: DELETE /api/v1/members/{memberId} deactivates the member but does not delete their account or reassign their authored Cards. For automated offboarding at scale, SCIM deprovisioning (PATCH /scim/v2/Users/{id} with active=false) is the preferred path to keep the identity graph between your IdP and Guru in sync. REST-only offboarding leaves content orphaned and requires manual content reassignment.

Provision a new employee via SCIM (Enterprise)

1. Ensure SSO (SAML) is active in Guru Settings.
2. Navigate to Guru Settings > SCIM Provisioning and generate a SCIM Bearer token.
3. Configure the SCIM app in Okta or Azure AD with the Guru SCIM base URL and Bearer token.
4. Assign the user to the Guru SCIM app in the IdP.
5. IdP sends POST /scim/v2/Users with user attributes; Guru creates the member as ACTIVE.
6. Optionally push group membership via PATCH /scim/v2/Groups/{id} to assign collection access.

Watch out for: If SSO is not active, SCIM provisioning will not function. Verify SSO login works before enabling SCIM.

Invite a user and assign to a group via REST API

1. POST /api/v1/members/invite with {"emails": ["newuser@example.com"], "role": "MEMBER"}.
2. Poll GET /api/v1/members until the user's status changes from PENDING to ACTIVE (user must accept invite).
3. Retrieve the member's UUID from the GET /api/v1/members response.
4. POST /api/v1/groups/{groupId}/members with {"email": "newuser@example.com"} to add to the target group.

Watch out for: Group membership cannot be set until the user accepts the invite and status is ACTIVE.

Offboard a user (deactivate and remove from groups)

1. GET /api/v1/members to find the member's UUID by email.
2. DELETE /api/v1/members/{memberId} to deactivate the member from the team.
3. If using SCIM: IdP deprovision event sends PATCH /scim/v2/Users/{id} with active=false, which Guru processes automatically.

Watch out for: REST API DELETE deactivates the user but does not remove their authored content. SCIM deprovisioning is preferred for automated offboarding to ensure IdP and Guru stay in sync.

The most common integration trap is assuming the REST API and SCIM API share authentication. They do not - a valid REST API token will be rejected by the SCIM endpoint, and vice versa. Teams building identity graph automation across both flows must manage two separate credential lifecycles.

A second trap is the PENDING status on REST-invited users. Downstream group assignments and Collection access grants will silently fail if attempted before the user accepts their invite and reaches ACTIVE status. Any automation pipeline that provisions group membership immediately after invite must include a status-check gate.

Role values are Guru-specific enums (MEMBER, AUTHOR, COLLECTION_OWNER, CORE_USER, ADMIN). SCIM role mapping must be explicitly configured in the IdP; generic SCIM role attributes will not map correctly without that configuration.

Finally, the REST API has no webhook support for user lifecycle events - event-driven pipelines must poll GET /api/v1/members or rely on IdP-side triggers via SCIM.