ForSURE.access_management

Access Management API

The Access Management API provides comprehensive functionality for managing users, roles, permissions, and organizational connections within your ForSURE account. This module enables you to control who has access to your organization's data and what actions they can perform.

Overview

The Access Management API handles all aspects of user and access control:

  • User Management: Add, remove, and view users within your organization
  • Role Management: Assign and modify permissions through role-based access control
  • Invitation System: Connect organizations through an invitation workflow (e.g., customer-agency relationships)
  • API Token Management: Generate tokens for programmatic access
  • Organization Switching: Change the active organization context for users with multiple organization access

Core Capabilities

User Management

Manage users within your organization:

  • List Users: Retrieve all users in your organization with their roles and permissions (GET /access)
  • Add Users: Add existing users to your organization (POST /access/add)
  • Remove Users: Remove users from your organization (POST /access/delete)
  • View User Details: See which roles each user has and whether you can edit them

Role Management

Control what users can do through role-based permissions:

  • View Available Roles: Get all roles grouped by category (GET /access/roles)
  • Edit User Roles: Add or remove roles for specific users (POST /access/edit)
  • Agency Role Management: Manage roles for agency connections (GET /access/invite/{connection_id}/agency-roles, POST /access/invite/{connection_id}/agency-roles/edit)

Roles are organized into categories (e.g., USER, ORDERS, REPORTS) and control access to different parts of the system. You can only assign roles that you have access to.

Invitation System

Connect your organization with other organizations (e.g., customers inviting agencies or vice versa):

  • Create Invitations: Invite users from other organizations to establish a connection (POST /access/invite)
  • List Invitations: View all invitations related to your organization (GET /access/invite)
  • Accept Invitations: Accept pending invitations using the token from the invitation email (POST /access/invite/accept)
  • Reject Invitations: Decline invitations from either side of the connection (POST /access/invite/{invitation_id}/reject)
  • Resend Invitations: Resend invitation emails for pending invitations older than 2 days (POST /access/invite/{invitation_id}/resend)

The invitation system supports bidirectional connections:

  • Customer-initiated: Customers invite agencies to access their data
  • Agency-initiated: Agencies invite customers to connect

When an invitation is accepted, the connection is established, client records are created, and users are added to the appropriate groups. Both parties receive notifications about invitation status changes.

API Token Management

Generate tokens for programmatic access without user authentication:

  • Create API Tokens: Generate new API tokens for your organization (POST /access/add-api-token)
  • Token Usage: Use tokens in the Authorization header for API requests

Important: Store tokens securely as they cannot be retrieved again after creation. API tokens are associated with your organization and inherit its permissions.

Organization Context

For users with access to multiple organizations:

  • Switch Organizations: Change your active organization context (POST /access/switch-company)

This is useful when you need to work with data from different organizations. The system supports both exact name matching and fuzzy matching for organization names.

Common Workflows

Adding a New User to Your Organization

  1. Add the user: POST /access/add with the user's email
  2. Assign roles: POST /access/edit to grant appropriate permissions
  3. Verify access: GET /access to confirm the user appears in your organization

Inviting an Agency to Access Your Data

  1. Create invitation: POST /access/invite with the agency user's email, company name, and relation type
  2. Monitor status: GET /access/invite to see invitation status
  3. Manage roles (after acceptance): POST /access/invite/{connection_id}/agency-roles/edit to control what the agency can access
  4. Resend if needed: POST /access/invite/{invitation_id}/resend if the invitation email wasn't received

Setting Up Programmatic Access

  1. Generate token: POST /access/add-api-token to create a new API token
  2. Store securely: Save the token from the response (it won't be shown again)
  3. Use in requests: Include the token in the Authorization: Bearer <token> header for API calls

Managing User Permissions

  1. View current roles: GET /access/roles to see available roles
  2. Check user permissions: GET /access to see what roles each user has
  3. Update roles: POST /access/edit to add or remove roles for specific users

Permissions

The Access Management API uses the following permission roles:

  • USER_VIEW: Required to view users and invitations
  • USER_EDIT: Required to modify user roles
  • USER_ADD: Required to add users or create invitations
  • USER_DELETE: Required to remove users from the organization

These permissions are hierarchical - users with USER_EDIT can typically view users, and users with USER_ADD can typically view invitations.

Response Format

All endpoints follow a consistent response format:

  • Success responses: Return status code 200 with the requested data or a SuccessResponse object
  • Error responses: Return appropriate HTTP status codes (400, 401, 403, 500) with error details

The SuccessResponse format:

{
  "status": "success",
  "message": "OK",
  "data": { /* optional additional data */ }
}

Authentication

All endpoints (except POST /access/invite/accept) require authentication via:

  • Bearer token in the Authorization header
  • The token must be associated with a user or API token that has the required permissions

The POST /access/invite/accept endpoint uses the invitation token instead of user authentication.

Best Practices

  1. Principle of Least Privilege: Only assign roles that users actually need
  2. Regular Audits: Periodically review user access using GET /access to ensure appropriate permissions
  3. Secure Token Storage: Store API tokens securely and rotate them periodically
  4. Monitor Invitations: Regularly check pending invitations to ensure timely acceptance
  5. Organization Context: Be aware of which organization context you're operating in when making requests

Getting Started

  1. View your organization's users: GET /access to see current users and their roles
  2. Check available roles: GET /access/roles to understand what permissions you can assign
  3. Add a user: POST /access/add to invite an existing user to your organization
  4. Assign permissions: POST /access/edit to grant appropriate roles

For detailed endpoint documentation, see the inline API documentation.