📖 Looking for karrio's legacy docs? Visit docs.karrio.io

User Management

Community Edition
Basic Auth

Every Karrio project comes with comprehensive user management capabilities, providing organization-based access control, role-based permissions, user invitations, and secure authentication for enterprise deployments.

Features

Organization-Based Access Control

You don’t have to build user management from scratch. Our system provides multi-organization support with isolated user access and resource management.

User Management Dashboard

Screenshot: User roles, permissions, and organization management interface

Role-Based Permissions

Assign granular permissions with predefined roles or create custom roles tailored to your business needs.

User Invitations & Onboarding

Send email invitations with automatic user onboarding and role assignment for seamless team collaboration.

Secure Authentication

JWT-based authentication with token management, refresh capabilities, and optional two-factor authentication.

Audit & Activity Tracking

Monitor user actions, access patterns, and permission changes with comprehensive audit trails.

Additional features

  • Karrio extends user management with API key management and rate limiting controls.
  • Every user interaction includes automatic session management and security monitoring.
  • Karrio manages user preferences and customizable dashboard configurations.
  • Support for SSO integration and external authentication providers.

Data Flow

User Authentication & Authorization Flow

API Reference

REST API

User Registration (Sign Up)

1curl -X POST "https://api.karrio.io/api/register" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "email": "newuser@example.com",
5    "password1": "secure_password123",
6    "password2": "secure_password123",
7    "first_name": "John",
8    "last_name": "Doe"
9  }'

Response:

1{
2  "user": {
3    "id": "usr_1234567890",
4    "email": "newuser@example.com",
5    "first_name": "John",
6    "last_name": "Doe",
7    "is_active": false,
8    "date_joined": "2024-01-15T08:00:00Z"
9  },
10  "message": "Verification email sent. Please check your email to activate your account."
11}

Email Verification

1curl -X POST "https://api.karrio.io/api/verify-email" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "key": "verification_token_from_email"
5  }'

Response:

1{
2  "detail": "Email verified successfully. Your account is now active."
3}

User Authentication (Sign In)

1curl -X POST "https://api.karrio.io/api/token" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "username": "user@example.com",
5    "password": "secure_password"
6  }'

Response:

1{
2  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE2NDI2ODEyMDB9.xyz",
3  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE2NDI3Njc2MDB9.abc",
4  "user": {
5    "id": "usr_1234567890",
6    "email": "user@example.com",
7    "first_name": "John",
8    "last_name": "Doe",
9    "is_active": true,
10    "date_joined": "2024-01-15T08:00:00Z"
11  }
12}

Password Reset Request

1curl -X POST "https://api.karrio.io/api/password/reset" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "email": "user@example.com"
5  }'

Response:

1{
2  "detail": "Password reset email sent. Please check your email for reset instructions."
3}

Password Reset Confirm

1curl -X POST "https://api.karrio.io/api/password/reset/confirm" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "uid": "user_id_from_email",
5    "token": "reset_token_from_email",
6    "new_password1": "new_secure_password123",
7    "new_password2": "new_secure_password123"
8  }'

Response:

1{
2  "detail": "Password has been reset successfully."
3}

Refresh Token

1curl -X POST "https://api.karrio.io/api/token/refresh" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE2NDI3Njc2MDB9.abc"
5  }'

Response:

1{
2  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE2NDI2ODEyMDB9.new_token"
3}

Verify Token

1curl -X POST "https://api.karrio.io/api/token/verify" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE2NDI2ODEyMDB9.xyz"
5  }'

Response (Valid Token):

1{
2  "valid": true,
3  "user": {
4    "id": "usr_1234567890",
5    "email": "user@example.com",
6    "organizations": [
7      {
8        "id": "org_1234567890",
9        "name": "Acme Corporation",
10        "role": "admin"
11      }
12    ]
13  }
14}

Get Current User

1curl -X GET "https://api.karrio.io/v1/users/me" \
2  -H "Authorization: Token YOUR_API_KEY"

Response:

1{
2  "id": "usr_1234567890",
3  "email": "user@example.com",
4  "first_name": "John",
5  "last_name": "Doe",
6  "is_active": true,
7  "date_joined": "2024-01-15T08:00:00Z",
8  "organizations": [
9    {
10      "id": "org_1234567890",
11      "name": "Acme Corporation",
12      "role": "admin",
13      "permissions": ["create_shipments", "manage_users", "view_analytics"]
14    }
15  ]
16}

GraphQL API

User Registration Mutation

1mutation RegisterUser($input: RegisterUserMutationInput!) {
2  register_user(input: $input) {
3    user {
4      id
5      email
6      first_name
7      last_name
8      is_active
9      date_joined
10    }
11    errors {
12      field
13      messages
14    }
15  }
16}

Variables:

1{
2  "input": {
3    "email": "newuser@example.com",
4    "password1": "secure_password123",
5    "password2": "secure_password123",
6    "first_name": "John",
7    "last_name": "Doe"
8  }
9}

Response:

1{
2  "data": {
3    "register_user": {
4      "user": {
5        "id": "usr_1234567890",
6        "email": "newuser@example.com",
7        "first_name": "John",
8        "last_name": "Doe",
9        "is_active": false,
10        "date_joined": "2024-01-15T08:00:00Z"
11      },
12      "errors": []
13    }
14  }
15}

Verify Email Mutation

1mutation VerifyEmail($input: VerifyEmailMutationInput!) {
2  verify_email(input: $input) {
3    success
4    errors {
5      field
6      messages
7    }
8  }
9}

Variables:

1{
2  "input": {
3    "key": "verification_token_from_email"
4  }
5}

Response:

1{
2  "data": {
3    "verify_email": {
4      "success": true,
5      "errors": []
6    }
7  }
8}

Token Authentication Mutation

1mutation TokenAuth($input: TokenAuthMutationInput!) {
2  token_auth(input: $input) {
3    token
4    refresh_token
5    user {
6      id
7      email
8      first_name
9      last_name
10      is_active
11    }
12    errors {
13      field
14      messages
15    }
16  }
17}

Variables:

1{
2  "input": {
3    "username": "user@example.com",
4    "password": "secure_password"
5  }
6}

Response:

1{
2  "data": {
3    "token_auth": {
4      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE2NDI2ODEyMDB9.xyz",
5      "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE2NDI3Njc2MDB9.abc",
6      "user": {
7        "id": "usr_1234567890",
8        "email": "user@example.com",
9        "first_name": "John",
10        "last_name": "Doe",
11        "is_active": true
12      },
13      "errors": []
14    }
15  }
16}

Refresh Token Mutation

1mutation RefreshToken($input: RefreshTokenMutationInput!) {
2  refresh_token(input: $input) {
3    token
4    errors {
5      field
6      messages
7    }
8  }
9}

Variables:

1{
2  "input": {
3    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE2NDI3Njc2MDB9.abc"
4  }
5}

Response:

1{
2  "data": {
3    "refresh_token": {
4      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VybmFtZSI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE2NDI2ODQyMDB9.new_token",
5      "errors": []
6    }
7  }
8}

Password Reset Request Mutation

1mutation PasswordReset($input: PasswordResetMutationInput!) {
2  password_reset(input: $input) {
3    success
4    errors {
5      field
6      messages
7    }
8  }
9}

Variables:

1{
2  "input": {
3    "email": "user@example.com"
4  }
5}

Response:

1{
2  "data": {
3    "password_reset": {
4      "success": true,
5      "errors": []
6    }
7  }
8}

Password Reset Confirm Mutation

1mutation PasswordResetConfirm($input: PasswordResetConfirmMutationInput!) {
2  password_reset_confirm(input: $input) {
3    success
4    errors {
5      field
6      messages
7    }
8  }
9}

Variables:

1{
2  "input": {
3    "uid": "user_id_from_email",
4    "token": "reset_token_from_email",
5    "new_password1": "new_secure_password123",
6    "new_password2": "new_secure_password123"
7  }
8}

Response:

1{
2  "data": {
3    "password_reset_confirm": {
4      "success": true,
5      "errors": []
6    }
7  }
8}

Query Current User

1query GetCurrentUser {
2  user {
3    id
4    email
5    first_name
6    last_name
7    is_active
8    date_joined
9    organizations {
10      id
11      name
12      role
13      permissions
14    }
15  }
16}

Response:

1{
2  "data": {
3    "user": {
4      "id": "usr_1234567890",
5      "email": "user@example.com",
6      "first_name": "John",
7      "last_name": "Doe",
8      "is_active": true,
9      "date_joined": "2024-01-15T08:00:00Z",
10      "organizations": [
11        {
12          "id": "org_1234567890",
13          "name": "Acme Corporation",
14          "role": "admin",
15          "permissions": ["create_shipments", "manage_users", "view_analytics"]
16        }
17      ]
18    }
19  }
20}

Query Users (Admin Only)

1query GetUsers($filter: UserFilter, $pagination: PaginationInput) {
2  users(filter: $filter, pagination: $pagination) {
3    edges {
4      node {
5        id
6        email
7        first_name
8        last_name
9        is_active
10        date_joined
11        organizations {
12          id
13          name
14          role
15        }
16      }
17    }
18    pageInfo {
19      hasNextPage
20      hasPreviousPage
21      startCursor
22      endCursor
23    }
24  }
25}

Variables:

1{
2  "filter": {
3    "is_active": true,
4    "organization_id": "org_1234567890"
5  },
6  "pagination": {
7    "first": 10
8  }
9}

Response:

1{
2  "data": {
3    "users": {
4      "edges": [
5        {
6          "node": {
7            "id": "usr_1234567890",
8            "email": "user@example.com",
9            "first_name": "John",
10            "last_name": "Doe",
11            "is_active": true,
12            "date_joined": "2024-01-15T08:00:00Z",
13            "organizations": [
14              {
15                "id": "org_1234567890",
16                "name": "Acme Corporation",
17                "role": "admin"
18              }
19            ]
20          }
21        }
22      ],
23      "pageInfo": {
24        "hasNextPage": false,
25        "hasPreviousPage": false,
26        "startCursor": "cursor1",
27        "endCursor": "cursor1"
28      }
29    }
30  }
31}

Update User Profile Mutation

1mutation UpdateUserProfile($input: UpdateUserProfileMutationInput!) {
2  update_user_profile(input: $input) {
3    user {
4      id
5      email
6      first_name
7      last_name
8    }
9    errors {
10      field
11      messages
12    }
13  }
14}

Variables:

1{
2  "input": {
3    "first_name": "John Updated",
4    "last_name": "Doe Updated"
5  }
6}

Response:

1{
2  "data": {
3    "update_user_profile": {
4      "user": {
5        "id": "usr_1234567890",
6        "email": "user@example.com",
7        "first_name": "John Updated",
8        "last_name": "Doe Updated"
9      },
10      "errors": []
11    }
12  }
13}

Send User Invitations

1mutation SendInvitations($input: SendInvitationsMutationInput!) {
2  send_invitations(input: $input) {
3    invitations {
4      id
5      email
6      organization {
7        id
8        name
9      }
10      role
11      expires_at
12    }
13    errors {
14      field
15      messages
16    }
17  }
18}

Variables:

1{
2  "input": {
3    "emails": ["newuser@example.com", "colleague@example.com"],
4    "organization_id": "org_1234567890",
5    "role": "user"
6  }
7}

Response:

1{
2  "data": {
3    "send_invitations": {
4      "invitations": [
5        {
6          "id": "inv_1234567890",
7          "email": "newuser@example.com",
8          "organization": {
9            "id": "org_1234567890",
10            "name": "Acme Corporation"
11          },
12          "role": "user",
13          "expires_at": "2024-01-22T10:30:00Z"
14        }
15      ],
16      "errors": []
17    }
18  }
19}

User Roles & Permissions

Standard Roles

Built-in roles with predefined permission groups:

Owner

  • Permissions: manage_org_owner
  • Capabilities: Complete organization ownership and control
  • Restrictions: Only available to organization owners

Admin

  • Permissions: manage_team, manage_apps, manage_carriers
  • Capabilities: Team management, application settings, carrier connections
  • Restrictions: Cannot transfer organization ownership

Developer

  • Permissions: manage_webhooks
  • Capabilities: Webhook configuration and API integrations
  • Restrictions: Limited to development and integration tasks

Member

  • Permissions: manage_data, manage_orders, manage_pickups, manage_trackers, manage_shipments
  • Capabilities: Core shipping operations, order management, tracking
  • Restrictions: Cannot manage users or organization settings

Permission Groups

The actual permission system uses these groups:

1{
2  "permission_groups": [
3    "manage_apps",
4    "manage_team",
5    "manage_system",
6    "manage_orders",
7    "manage_data",
8    "manage_pickups",
9    "manage_carriers",
10    "manage_trackers",
11    "manage_webhooks",
12    "manage_shipments",
13    "manage_org_owner"
14  ]
15}

Organization Management

Organization management is handled by a separate system. For detailed information about creating organizations, managing teams, and organization-level features, see our Multi-Organizations documentation.

Use Cases

Team Collaboration

Perfect for teams managing shipping operations:

  • Role Assignment: Assign appropriate roles based on responsibilities
  • Access Control: Limit access to sensitive operations and data
  • Audit Trail: Track who performed what actions and when
  • Invitation Workflow: Easily onboard new team members

Enterprise Deployment

Designed for large organizations with complex requirements:

  • Permission Groups: Fine-grained control over feature access using permission groups
  • User Provisioning: Automated user creation and role assignment
  • Compliance Reporting: Detailed audit logs for compliance requirements
  • Multi-Organization Support: See Multi-Organizations for details

Partner Integration

Enable external partners and vendors to access specific resources:

  • Limited Access: Provide specific permission groups for controlled access
  • Resource Isolation: Keep partner data separate using organizational boundaries
  • Temporary Access: Set expiration dates for partner accounts
  • Activity Monitoring: Track partner usage and access patterns

Security Features

Authentication Options

Standard Authentication

Username/password authentication
1curl -X POST "https://api.karrio.io/api/token" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "username": "user@example.com",
5    "password": "secure_password"
6  }'

Two-Factor Authentication

2FA authentication with OTP
1curl -X POST "https://api.karrio.io/api/token/verified" \
2  -H "Content-Type: application/json" \
3  -d '{
4    "username": "user@example.com",
5    "password": "secure_password",
6    "otp_token": "123456"
7  }'

API Key Management

Generate and manage API keys for programmatic access:

API keys are managed through the admin dashboard
1// Use the web interface to create and manage API keys
2// Each key can be assigned specific permissions and expiration dates

Integration Examples

User Onboarding Workflow

User invitations are handled through the admin dashboard
1// Invitations are sent via email with secure acceptance links
2// Users create their accounts by following the invitation link

Permission Management

User permissions are managed through the admin dashboard
1// Admins can update permission groups for team members
2// Changes take effect immediately for the user's session

Getting Started

Ready to set up user management in Karrio? Follow these steps:

  1. Register users and handle email verification
  2. Assign appropriate permission groups based on responsibilities
  3. Set up authentication for your application
  4. Configure role-based access for different user types

Next Steps

  • Learn about multi-orgs for advanced organization management
  • Explore webhooks for user activity notifications
  • Set up API logs to monitor user API usage
  • Configure admin console for centralized management