Movement Services | RMIS - Authentication

RMIS (Red Meat Industry Services) is the Movement Service for livestock in South Africa. RMIS uses GLN-based (Global Location Number) authentication to validate requests and authenticate participants.

Overview

This document covers authentication for RMIS’s livestock movement and registration services.

Flow

RMIS uses a two-tier authentication model combining:

API Key (Subscription Key): Service provider authentication provided by RMIS
Participant Token: Property/GLN-specific token that identifies the holding

Authentication Process

┌──────────────┐
│   Client     │
└──────┬───────┘
       │
       │ 1. Submit Transaction with:
       │    - API Key (ServiceProviderAuth.SubscriptionKey)
       │    - Participant Token (PropertyAuth.Password)
       │    - Transaction data
       │
       ▼
┌──────────────────────────┐
│    EasiTrace API         │
│  (MovementServices)      │
└──────┬───────────────────┘
       │
       │ 2. Extract credentials from transaction/auth
       │
       ▼
┌──────────────────────────┐
│   ParticipantAuthToken   │
│       Handler            │
│  - Validates API Key     │
│  - Exchanges Participant │
│    Token for Bearer      │
└──────┬───────────────────┘
       │
       │ 3. Call RMIS API:
       │    GET /api/v1/participants/accessToken
       │    Header: Authorization: ApiKey {api-key}
       │    Query: ParticipantToken={participant-token}
       │
       ▼
┌──────────────────────────┐
│    RMIS API Service      │
│  (South Africa)          │
└──────┬───────────────────┘
       │
       │ 4. Return:
       │    { "accessToken": "bearer-token-123..." }
       │
       ▼
┌──────────────────────────┐
│   Authenticated Request  │
│   Header: Authorization: │
│   Bearer {bearer-token}  │
└──────┬───────────────────┘
       │
       │ 5. Call RMIS service endpoints
       │    (Create movements, register animals, etc.)
       │
       ▼
┌──────────────────────────┐
│    RMIS API Response     │
│    Success/Failure       │
└──────────────────────────┘

Prerequisites

To authenticate with RMIS, you will need:

From RMIS Service Provider

API Key (Subscription Key)
- Uniquely identifies your organization/tenant
- Provided by RMIS during onboarding
- Format: alphanumeric string
- Must be included with every request
- Keep this credential secure and never expose in client-side code
Participant Token
- Unique to each User on RMIS
- Must be registered with RMIS first
- Changed periodically by RMIS for security

GLN Registration

Before you can use RMIS:

Your organization must be registered with RMIS
Each property/holding must have a valid 13-digit GLN (Global Location Number)
Each GLN must have a corresponding Participant Token issued by RMIS

GLN (Global Location Number)

What is a GLN?

A Global Location Number (GLN) is an internationally standardized identifier assigned to physical and digital locations. In South Africa’s livestock industry (RMIS), GLNs uniquely identify:

Properties/Holdings: Individual farms, ranches, or feedlots
Facilities: Specific locations within a property (buildings, pens, grazing areas)
Business Entities: Abattoirs, traders, transport companies

GLN Format for RMIS

Length: Exactly 13 digits
Format: Numeric only (^\d{13}$)
Example: 1234567890123
Examples with context:
- Departure (source) property: 5000123456001 (farm sending animals)
- Arrival (destination) property: 5000987654002 (farm receiving animals)

GLN Assignment

GLNs are assigned through the official GS1 system:

GS1 South Africa: Maintains the GLN registry
Registration Process:
- Organization applies to GS1 SA
- GLN is assigned to each location
- GLN is registered in both GS1 and RMIS systems
Verification: RMIS validates GLNs against the GS1 registry

GLN Validation in RMIS

Every RMIS transaction validates that:

GLN is exactly 13 digits
GLN is registered in RMIS
The authenticated participant owns/has access to the GLN
GLN is active and not suspended

Setup

Obtaining GLN Credentials

Step 1: Register with RMIS

Contact RMIS (Red Meat Industry Services) - South Africa
Provide:
- Organization name and details
- List of properties to register (with physical addresses)
RMIS will:
- Verify your organization
- Assign/link GLNs to your properties
- Issue an API Key for your organization

Step 2: Obtain Participant Tokens

For each property GLN:

RMIS issues a unique Participant Token
Store this securely (typically in secure configuration or vault)
Each property has its own Participant Token
Tokens are regenerated periodically by RMIS for security

Step 3: Store Credentials

Recommended approach:

Configuration/Secrets:
├── RMIS:ApiKey = "your-api-key-from-rmis"
├── RMIS:Properties:
│   ├── GLN_1234567890123 = "participant-token-for-this-gln"
│   ├── GLN_5000123456001 = "participant-token-for-this-gln"
│   └── GLN_5000987654002 = "participant-token-for-this-gln"

Do NOT:

Hardcode credentials in source code
Commit tokens to version control
Share tokens via email or chat
Store in client-side code

Transaction Example with Authentication

Complete Transaction with Embedded Auth Token

For direct authentication, the participant code may be included in the serviceAuthToken for the transaction:

{
  "reference": "RMIS-MOV-OFF-2024-001",
  "transactionDate": "2024-03-15T08:30:00Z",
  "type": "MOV-OFF",
  "serviceTag": "RMIS",
  "speciesCode": "C",
  "propertyIdentifier": "1234567890123",
  "serviceAuthToken": "your-participant-code-from-rmis",
  "fields": {
    "RMIS.Departure.Gln": "1234567890123",
    "RMIS.Destination.Gln": "9876543210987",
    "RMIS.Departure.Date": "2024-03-15",
    "RMIS.Departure.Latitude": "-33.8688",
    "RMIS.Departure.Longitude": "18.8319"
  },
  "animals": [
    {
      "rfid": "982000123456789",
      "visual": "ZA100001001234"
    },
    {
      "rfid": "982000123456790",
      "visual": "ZA100001001235"
    }
  ]
}

Transaction with PropertyAuth and ServiceProviderAuth

If not providing a bearer token, EasiTrace will automatically obtain one using participant credentials:

{
  "reference": "RMIS-MOV-ON-2024-002",
  "transactionDate": "2024-03-15T14:45:00Z",
  "type": "MOV-ON",
  "serviceTag": "RMIS",
  "speciesCode": "C",
  "propertyIdentifier": "9876543210987",
  "fields": {
    "RMIS.Destination.Gln": "9876543210987",
    "RMIS.Destination.ArrivalDate": "2024-03-15",
    "RMIS.Destination.DeceasedCount": "0",
    "RMIS.Destination.Latitude": "-33.9249",
    "RMIS.Destination.Longitude": "18.9534"
  },
  "animals": [
    {
      "rfid": "982000123456789",
      "visual": "ZA100001001234"
    },
    {
      "rfid": "982000123456790",
      "visual": "ZA100001001235"
    }
  ]
}

With corresponding HTTP request including auth:

POST /api/transactions
Content-Type: application/json

{
  "transaction": { ... },
  "authentication": {
    "serviceProviderAuth": {
      "subscriptionKey": "your-api-key-from-rmis"
    },
    "propertyAuth": {
      "password": "participant-token-for-the-gln"
    }
  }
}

RMIS Specific Requirements

Authentication Requirements Per Transaction Type

Transaction Type	API Key Required	Participant Token Required	GLN Required
MOV-OFF (Movement Off)	✓	✓	✓ (propertyIdentifier)
MOV-ON (Movement On)	✓	✓	✓ (propertyIdentifier)
MOV-IN (Incoming Movements)	✓	✓	✓ (propertyIdentifier)
REG (Register)	✓	✓	✓ (propertyIdentifier)
RET (Retag)	✓	✓	✓ (propertyIdentifier)
UPDATEMOV-OFF	✓	✓	✓ (propertyIdentifier)
UPDATEMOV-ON	✓	✓	✓ (propertyIdentifier)
MOV-ON-DEL (Reject)	✓	✓	✓ (propertyIdentifier)

Multiple GLN Scenario

If your organization manages multiple properties:

// Example C# - Managing Multiple GLNs

// Organization-level API Key (same for all GLNs)
const string ApiKey = "org-api-key-xyz";

// Property-specific credentials
var properties = new Dictionary<string, string>
{
    { "1234567890123", "participant-token-property-1" },
    { "5000123456001", "participant-token-property-2" },
    { "5000987654002", "participant-token-property-3" }
};

// When submitting transaction for a specific property:
var transaction = CreateMovementTransaction(
    propertyGln: "5000123456001",  // Must match one of your properties
    animals: animalList
);

var auth = new Authentication
{
    ServiceProviderAuth = new ServiceProviderAuthentication 
    { 
        SubscriptionKey = ApiKey  // Organization API Key
    },
    PropertyAuth = new PropertyAuthentication 
    { 
        Password = properties["5000123456001"]  // GLN-specific token
    }
};

await easitraceClient.SubmitTransactionAsync(transaction, auth);

Credential Validation

Validation Checks Performed by RMIS

When a transaction is received, RMIS validates:

API Key Validation
- ✓ API Key is valid and active
- ✓ API Key belongs to an authorized organization
- ✓ Organization hasn’t exceeded rate limits
Participant Token Validation
- ✓ Participant Token is valid for the specified GLN
- ✓ Token hasn’t expired
- ✓ Token is associated with an active property
- ✓ Property (GLN) exists in RMIS system
Bearer Token Validation
- ✓ Token is current (not expired)
- ✓ Token is for the correct participant
- ✓ Token signature is valid
GLN Validation
- ✓ Exactly 13 digits
- ✓ Registered in RMIS
- ✓ Authenticated participant has access
- ✓ GLN is active (not suspended/deleted)

Common Authentication Errors

Error	Cause	Resolution
`Authentication.InvalidApiKey`	API Key is invalid or missing	Verify API Key from RMIS onboarding email
`Authentication.InvalidParticipantToken`	Participant Token is invalid or expired	Request new token from RMIS support
`Authentication.TokenExpired`	Bearer token has expired	Get new token (automatic via EasiTrace)
`Authentication.InvalidGln`	GLN not found or inactive	Verify 13-digit GLN format, confirm with RMIS
`Authentication.AccessDenied`	Participant can’t access this GLN	Confirm GLN belongs to your organization

Testing Authentication

Step 1: Validate API Key

GET https://web-tr-api-test.azurewebsites.net/api/v1/participants/accessToken
Headers:
  Authorization: ApiKey your-api-key
Query Parameters:
  ParticipantToken: your-participant-token

Success Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Failure Response:

{
  "accessToken": ""
}

Step 2: Validate with Bearer Token

POST https://web-tr-api-test.azurewebsites.net/api/v1/livestock/add
Headers:
  Authorization: Bearer {accessToken}
  Content-Type: application/json
Body: { ... livestock transfer data ... }

If bearer token is invalid or expired, you’ll receive a 401 Unauthorized response.

Test & Production Environments

Test Environment (Pre-Production)

Endpoint: https://web-tr-api-test.azurewebsites.net

Features:

Full functionality for testing
Mock data accepted
Higher rate limits for development
Test GLNs provided by RMIS
Non-persistent state (data may be reset)

Usage:

var testSettings = new RmisSettings
{
    WebServiceUrl = "https://web-tr-api-test.azurewebsites.net"
};

Test Credentials:

API Key (Test): test-api-key-12345
Participant Tokens (provided by RMIS for test GLNs):
  - GLN 5000000000001: test-participant-token-1
  - GLN 5000000000002: test-participant-token-2
  - GLN 5000000000003: test-participant-token-3

Test Scenario Example:

{
  "reference": "TEST-RMIS-001",
  "transactionDate": "2024-03-15T10:00:00Z",
  "type": "MOV-OFF",
  "serviceTag": "RMIS",
  "speciesCode": "C",
  "propertyIdentifier": "5000000000001",
  "fields": {
    "RMIS.Departure.Gln": "5000000000001",
    "RMIS.Destination.Gln": "5000000000002",
    "RMIS.Departure.Date": "2024-03-15",
    "RMIS.Departure.Latitude": "-33.8688",
    "RMIS.Departure.Longitude": "18.8319"
  },
  "animals": [
    {
      "rfid": "982000000000001",
      "visual": "TEST001001"
    }
  ]
}

Production Environment

Endpoint: https://web-api.rmis.co.za or configured RMIS production endpoint

Features:

Live livestock movement data
Data persisted for compliance/audit
Standard rate limits
Real GLNs for your organization
Availability SLA guaranteed

Credentials:

Real API Key issued during production onboarding
Real Participant Tokens for each property
Must be obtained from RMIS directly

Important:

✓ Use different API Key/tokens for production vs test
✓ Rotate credentials periodically per RMIS security policy
✓ Enable request signing/validation where available
✓ Log all transactions for compliance
✓ Monitor authentication failures

Migration from Test to Production

Obtain Production Credentials
- Contact RMIS production support
- Provide list of properties for production

Update Configuration

// Development
var devSettings = new RmisSettings 
{ 
    WebServiceUrl = "https://web-tr-api-test.azurewebsites.net"
};

// Production
var prodSettings = new RmisSettings 
{ 
    WebServiceUrl = "https://web-api.rmis.co.za"
};

Verify All Transactions
- Test each transaction type with real GLNs
- Verify animals are recorded correctly
- Check incoming movements show expected data
- Monitor for any authentication issues
Enable Monitoring
- Track authentication success/failure rates
- Alert on repeated auth failures
- Monitor credential expiry warnings

For more information about submitting Transactions see Submitting transactions.

For RMIS service details, see RMIS Services Overview.

For general authentication concepts, see Services Authentication.