Skip to main content

​
Actor Registration

Before beginning integration, you’ll need to register with Legitmark as an authenticated actor. Contact our integration team to receive:
  • Actor API Key (format: leo_xxxxxxxxx) for application authentication
  • Actor Application UUID identifying your organization in our system
  • Base API URL for all requests: https://api.Legitmark.com
Contact [email protected] to begin the registration process.

​
Authentication Architecture

Legitmark implements a dual-authentication system designed for enterprise security requirements.

​
Application Authentication

Your API Key (x-api-key header) identifies your platform and authorizes access to Legitmark services. This key authenticates your application but does not identify individual users.

​
Actor Authentication

Actor Tokens (x-user-token header) securely identify individual actors without transmitting personally identifiable information (PII) in API requests. This design ensures compliance with data protection requirements while enabling actor-specific operations.

​
Security Model

After initial actor registration, all API communications use only non-PII tokens. Actor personal information is never transmitted in headers, URLs, or query parameters, meeting strict data protection standards.

​
Actor Token Management

​
Actor Registration Process

When an actor first accesses authentication features on your platform, register them with Legitmark to receive a secure token through the federation process: API Reference: POST /api/actor/users Required Data:
  • Your internal actor identifier (non-PII)
  • Actor email address (transmitted securely in request body)
  • Actor first and last name
  • Business name (company or organization name)
  • Certificate issuance name (name to appear on authentication certificates)
Response: You receive a secure token (format: lm_usr_a1b2c3d4e5f6) that represents this actor in all future API calls.

​
Token Storage and Usage

Store the mapping between your internal actor ID and the Legitmark token in your system. Use both authentication headers for all subsequent API requests: 
const headers = {
  'x-api-key': 'leo_xxxxxxxxx',                // Actor API key
  'x-user-token': 'lm_usr_a1b2c3d4e5f6',      // Secure actor token
  'Content-Type': 'application/json'
};

​
Actor Management Operations

API Reference: Actor Federation endpoints Available operations for managing actors:
  • Register new actors and receive secure tokens
  • Check actor mapping status for existing registrations
  • Update actor information when details change
  • Remove actor mappings when actors are deactivated

​
API Rate Limits

Legitmark implements multi-tier rate limiting to ensure platform stability and fair resource allocation: Actor-Level Limits: 1,000 requests per minute across all your actors
Individual Actor Limits: 60 requests per minute per individual actor token
Service Request Limits: 100 new authentication requests per hour per actor

​
Rate Limit Headers

All API responses include rate limit headers indicating current usage and remaining capacity: 
X-RateLimit-Limit-Actor: 1000
X-RateLimit-Remaining-Actor: 999
X-RateLimit-Limit-User: 60
X-RateLimit-Remaining-User: 59

​
Rate Limit Handling

When limits are exceeded, the API returns HTTP status 429 with retry timing information. Implement exponential backoff in your client code to handle rate limiting gracefully. API Reference: Rate Limits documentation for detailed handling strategies.

​
Security Best Practices

​
Token Management

  • Store actor tokens securely in encrypted storage
  • Never log actor tokens in application logs
  • Implement token rotation when security is compromised
  • Monitor for unusual token usage patterns

​
API Key Security

  • Restrict API key access to authorized systems only
  • Use environment variables for API key storage
  • Implement key rotation procedures
  • Monitor API key usage for anomalies

​
Request Security

  • Always use HTTPS for API communications
  • Validate webhook signatures (provided during setup)
  • Implement request timeout and retry logic
  • Use secure headers for all authenticated requests

​
Testing Authentication

​
Verify API Key

Test your API key with a simple service request: 
curl -X GET "https://api.Legitmark.com/api/services" \
  -H "x-api-key: your-api-key-here"

​
Test Actor Registration

Register a test actor to verify the complete authentication flow: API Reference: Use the Interactive API Reference to test actor registration with your actual credentials.

​
Next Steps

Once authentication is configured:
  1. Review Taxonomy to understand item classification
  2. Implement Workflow for service requests
  3. Set up Real-Time Updates for status notifications