Skip to main content

Organization API Example

This document describes the recommended sequence of API requests to display user details after login, including mapping the authentication provider user ID to the internal User.id, and fetching related data.

1. Get User by authProviderUserId​

Purpose: Map the external authentication provider user ID to the internal User record.

Request:

GET /users?authProviderUserId={authProviderUserId}

Response:

{
  "id": "user-123",
  "authProviderUserId": "external-abc",
  "role": "member",
  "userType": "user"
}

2. Get User Details​

Purpose: Fetch the full user profile using the internal User.id.

Request:

GET /users/{userId}

Response:

{
  "id": "user-123",
  "authProviderUserId": "external-abc",
  "role": "member",
  "userType": "user"
}

3. Get User's Teams (Memberships)​

Purpose: List all teams the user is a member of, including roles.

Request:

GET /users/{userId}/user-teams

Response:

[
  {
    "id": "ut1",
    "userId": "user-123",
    "teamId": "teamA",
    "role": "member",
    "status": "active",
    "joinedAt": "2025-01-01T12:00:00Z"
  }
]

Purpose: List relationships where the user is the source or target.

Request:

GET /user-links?sourceUserId={userId}
GET /user-links?targetUserId={userId}

Response:

[
  {
    "id": "link1",
    "sourceUserId": "user-123",
    "targetUserId": "user-456",
    "linkType": "partner",
    "description": "Linked to another organization"
  }
]

5. Accept Team Invitation & Share Profile​

Purpose: Applicant accepts a team invitation and shares one or more profiles with the team.

Step 1: Accept Invitation

PUT /team-invitations/{invitationId}
{
  "status": "accepted"
}

Response:

{
  "id": "ti2",
  "teamId": "teamA",
  "invitedUserId": "user-applicant1",
  "status": "accepted"
}

Step 2: Create UserTeam Membership

POST /user-teams
{
  "userId": "user-applicant1",
  "teamId": "teamA",
  "role": "member",
  "status": "active"
}

Response:

{
  "id": "ut10",
  "userId": "user-applicant1",
  "teamId": "teamA",
  "role": "member",
  "status": "active"
}

Step 3: Create and Share Profile

POST /user-profiles
{
  "userId": "user-applicant1",
  "userProfileSchemaId": "resume-schema",
  "name": "Applicant Resume",
  "data": { "summary": "Experienced analyst", "skills": ["Excel", "SQL"] }
}

Response:

{
  "id": "up1",
  "userId": "user-applicant1",
  "userProfileSchemaId": "resume-schema",
  "name": "Applicant Resume",
  "data": { "summary": "Experienced analyst", "skills": ["Excel", "SQL"] }
}
POST /user-profile-shares
{
  "userProfileId": "up1",
  "sharedWithTeamId": "teamA",
  "permission": "view"
}

Response:

{
  "id": "ups1",
  "userProfileId": "up1",
  "sharedWithTeamId": "teamA",
  "permission": "view"
}

6. Managing Roles & Permissions in Teams​

Purpose: Organizations can define custom roles for their teams, assign permissions, and manage user roles.

Step 1: List Roles for a Team

GET /teams/{teamId}/roles

Response:

[
  {
    "id": "role-owner",
    "teamId": "teamA",
    "name": "Owner",
    "description": "Full access to manage team",
    "permissions": ["manageMembers", "editTeam", "inviteUsers", "viewReports"]
  },
  {
    "id": "role-member",
    "teamId": "teamA",
    "name": "Member",
    "description": "Basic team member",
    "permissions": ["viewReports"]
  }
]

Step 2: Create a New Role

POST /teams/{teamId}/roles
{
  "name": "Admin",
  "description": "Can manage members and edit team",
  "permissions": ["manageMembers", "editTeam"]
}

Response:

{
  "id": "role-admin",
  "teamId": "teamA",
  "name": "Admin",
  "description": "Can manage members and edit team",
  "permissions": ["manageMembers", "editTeam"]
}

Step 3: Assign Role to User in Team

POST /user-teams
{
  "userId": "user-123",
  "teamId": "teamA",
  "teamRoleId": "role-admin",
  "status": "active"
}

Response:

{
  "id": "ut11",
  "userId": "user-123",
  "teamId": "teamA",
  "teamRoleId": "role-admin",
  "status": "active"
}

Step 4: Update Role Permissions

PUT /teams/{teamId}/roles/{roleId}
{
  "permissions": ["manageMembers", "editTeam", "inviteUsers"]
}

Response:

{
  "id": "role-admin",
  "teamId": "teamA",
  "name": "Admin",
  "description": "Can manage members and edit team",
  "permissions": ["manageMembers", "editTeam", "inviteUsers"]
}

Step 5: Delete a Role

DELETE /teams/{teamId}/roles/{roleId}

Response: 204 No Content

Notes​

  • Always use the internal User.id for all relationships and references in your API requests.
  • The authProviderUserId is only used for mapping the external identity to your internal user record.
  • You can improve and extend this documentation as your API evolves.
  • The applicant can repeat Step 3 to share multiple profiles.
  • All relationships use internal IDs (userId, teamId, userProfileId).
  • This flow is extensible for other scenarios (e.g., team member, organization).
  • Permissions are defined as strings (e.g., manageMembers, editTeam, inviteUsers, viewReports).
  • Each team can define its own roles and permissions.
  • UserTeam now references teamRoleId, not a free-text role.
  • This model supports granular access control for organizations and teams.