How to Create API Users and Tokens

Overview

API tokens in MachShip are created in MachShip on specific users and inherit all of that user's permissions, company access, and test mode settings.

When setting up integrations, it's best practice to create a new user for that integration so any actions taken by that API key are easily trackable back to that user and appropriate permissions can be provided.

It is advisable to setup a production and sandbox user for each integration - though it's not required.

You can opt to use a single user, and change that users mode from test to production when you're ready to go live.

How to Create An API User

Create A User

Creating a user for use with the API is the same as creating any other user.

1. Navigate to Admin and select Create User

You will need to set:

  • Username
  • Company
  • Password
  • Name
  • Surname
  • Email

Consider setting the username to something description to the integration.

For example, it may be Bills.Warehouse.Integration or similar.

2. Select the appropriate Test Mode setting

The test mode setting on a user provides a sandbox environment for development and testing.

Consignments created by test mode users are not billed, and not sent to the carriers on manifest.

The test mode options are best described as:
- User is in test mode - this is a test user and would only create test consignments
- Enabled to see test consignments - this is a production user, but able to see test consignments
- Disabled from seeing test consignments - this is a production user, and not able to see test consignments.

3. Role Assignment

Choose a role that matches your API requirements:

  1. Review the API endpoints you'll be using
  2. Check the permissions needed for each endpoint
  3. Select a role that includes all required permissions
  4. Avoid assigning unnecessary permissions

4. Save Your New User Click SAVE to create your new user.

Create Your API Token

  1. Navigate to View Users
  2. Locate and select the new API user
  3. Scroll to API Tokens section at the bottom
  4. Click Create API Token
  5. Enter a unique, descriptive name
  6. Copy and securely store the token

Important: Token values are only displayed once at creation. Store them securely as they cannot be retrieved later.

Understanding Users and Access

Company Structure

MachShip uses a hierarchical company structure. For example:

- Surefoot Enterprises
    - Surefoot Melbourne
    - Surefoot Sydney

User access follows this hierarchy:

  • Users at a child company (e.g., Surefoot Melbourne) only see data for their company
  • Users at a parent company (e.g., Surefoot Enterprises) see data for their company and all companies below

This hierarchy directly affects API access - tokens inherit the same visibility rules as their associated user.

The outcome of this is, if you want your user to view a company, ensure your user is at that company level or above.

User Roles

Each user is assigned a role that defines their permissions. Common roles include:

  • Dispatch:

    • Can create consignments
    • Cannot access settings
    • Limited to operational tasks

  • View Only:

    • Can view consignments
    • Cannot create or modify data
    • Read-only access

  • Admin:

    • Full system access
    • Can manage users and settings
    • Unrestricted permissions

API tokens inherit all permissions from their associated users role:

  • Company access level
  • Role-based permissions
  • Feature access
  • Test mode status

Common Issues

  1. Permission Errors

    • Token user has insufficient permissions
    • User assigned to wrong company
    • Role missing required access
    • Test mode mismatch

  2. Access Limitations

    • Token company level too low
    • Missing carrier account access
    • Restricted feature access
    • Role permissions insufficient

  3. Best Practices

    • Create dedicated API users
    • Use appropriate company level
    • Assign minimal required permissions
    • Document token purposes
    • Regular access review