Alpha (Mossland) Authentication: API Access & Security (2026)

Authentication overview

Authentication for Alpha (Mossland) API interactions focuses on verifying the identity of the requesting application or user to ensure secure and authorized access to Mossland's blockchain-integrated services. This is crucial for developers building location-based AR games, NFT-based gaming, and metaverse experiences within the Mossland ecosystem. The primary mechanisms involve API keys for general access and signature-based authentication for transactions requiring user authorization, such as those involving Moss Coin (MOC) or NFT assets. This dual approach addresses both application-level access control and user-specific transaction integrity, typical in blockchain environments.

The authentication process is designed to protect both the developer's application and the end-user's assets by ensuring that only legitimate requests are processed. Developers integrate these authentication methods into their applications to interact with Mossland's various components, including game logic, asset management, and blockchain operations. Understanding the specific requirements for each API endpoint is essential for successful integration, as some operations may only require an API key, while others demand a cryptographically signed payload.

Supported authentication methods

Alpha (Mossland) primarily supports two distinct authentication methods, each suited for different types of API interactions and security requirements:

1. API Keys: These are used for identifying the client application making the request. API keys typically grant access to public data or non-sensitive operations and are associated with a developer account. They help in tracking API usage and applying rate limits.
2. Signature-based Authentication: This method is employed for requests that involve sensitive operations, such as creating transactions, modifying user data, or interacting with blockchain assets. It requires the request payload to be signed using a private key associated with the user or application. The signature, often a Hash-based Message Authentication Code (HMAC) using SHA256, provides integrity and authenticity, proving that the request originated from the legitimate owner of the private key and has not been tampered with. This aligns with common practices for securing transactions in blockchain environments, as detailed in HMAC: Keyed-Hashing for Message Authentication.

The table below summarizes these methods:

Getting your credentials

To begin integrating with the Alpha (Mossland) API, developers must obtain the necessary credentials. The process typically involves registering as a developer and managing your keys through a dedicated developer portal. While specific steps may evolve, the general procedure outlined in the Mossland documentation often includes:

1. Developer Account Registration: Create an account on the official Mossland developer portal. This account will serve as your primary identity for accessing developer resources and managing your API integrations.
2. API Key Generation: Once registered, navigate to the API key management section within your developer dashboard. Here, you can generate new API keys for your applications. It's best practice to generate separate keys for different applications or environments (e.g., development, staging, production) to enhance isolation and security.
3. Private Key Management (for Signature-based Auth): For operations requiring signature-based authentication, you will need a private key. This key is often generated client-side or within a secure environment you control, associated with the Mossland wallet or identity used for transactions. Mossland's system will then verify signatures against the corresponding public key. Ensure these private keys are stored securely and never exposed in client-side code or public repositories.
4. Credential Storage: Upon generation, securely store your API keys and private keys. API keys should be treated as sensitive credentials, similar to passwords, and should not be hardcoded directly into your application's source code. Environment variables or secure configuration management systems are recommended for storage.

Always refer to the latest Mossland API documentation for the most up-to-date and detailed instructions on credential acquisition and management.

Authenticated request example

This example demonstrates a hypothetical authenticated request to a Mossland API endpoint using both an API Key and a signature for a sensitive operation. While the exact endpoint and payload may vary, the structure illustrates the principles of signature-based authentication.

Assume an endpoint /api/v1/user/transaction requires an API key in the header and a signed payload in the body for transferring MOC.

Request Details

• Method: POST
• Endpoint: https://api.moss.land/v1/user/transaction
• Headers:
  • Content-Type: application/json
  • X-API-KEY: YOUR_ALPHA_API_KEY
  • X-SIGNATURE: generated_signature_string
  • X-TIMESTAMP: current_unix_timestamp
• Body (JSON):

  
  {
    "fromAddress": "0x...your_address...",
    "toAddress": "0x...recipient_address...",
    "amount": "10.0",
    "currency": "MOC",
    "nonce": "unique_request_identifier"
  }
  

Signature Generation Logic (Conceptual)

import hmac
import hashlib
import json
import time

# Your credentials
api_key = "YOUR_ALPHA_API_KEY"
private_key = "YOUR_SECURE_PRIVATE_KEY" # This should be securely managed, not hardcoded

# Request data
request_body = {
  "fromAddress": "0x...your_address...",
  "toAddress": "0x...recipient_address...",
  "amount": "10.0",
  "currency": "MOC",
  "nonce": "unique_request_identifier"
}

# Convert body to canonical JSON string (no whitespace, sorted keys)
cannonical_body = json.dumps(request_body, separators=(',', ':'), sort_keys=True)

timestamp = str(int(time.time()))

# Concatenate elements for signing: Method + Path + Timestamp + CanonicalBody
# (Exact concatenation rules vary; consult Mossland docs)
string_to_sign = "POST" + "/v1/user/transaction" + timestamp + cannonical_body

# Generate HMAC-SHA256 signature
signature = hmac.new(
    private_key.encode('utf-8'),
    string_to_sign.encode('utf-8'),
    hashlib.sha256
).hexdigest()

print(f"X-API-KEY: {api_key}")
print(f"X-TIMESTAMP: {timestamp}")
print(f"X-SIGNATURE: {signature}")
print(f"Request Body: {cannonical_body}")

This Python snippet illustrates the process. The private_key should never be exposed in client-side code or public repositories. The exact signature generation algorithm, including the order of concatenation and encoding, must precisely match the specifications provided in the Mossland API documentation to ensure successful verification by the API.

Security best practices

Adhering to security best practices is paramount when authenticating with Alpha (Mossland) to protect your applications and user assets. These guidelines are general practices that apply widely to API integrations involving sensitive data and blockchain interactions:

• Secure Credential Storage: Never hardcode API keys or private keys directly into your application's source code. Use environment variables, secure configuration files, or dedicated secret management services (e.g., Google Cloud Secret Manager, AWS Secrets Manager) to store and retrieve credentials at runtime.
• Private Key Protection: Private keys, especially those used for signing blockchain transactions, must be kept extremely confidential. They should ideally reside in hardware security modules (HSMs), secure enclaves, or encrypted storage, and only be accessible by authorized processes. Avoid transmitting private keys over networks.
• Least Privilege Principle: Grant your API keys and associated accounts only the minimum necessary permissions required for your application to function. Avoid using a single key with broad administrative privileges for all operations.
• Regular Key Rotation: Periodically rotate your API keys and private keys. This practice limits the window of exposure should a key become compromised. Establish a regular schedule for key rotation and implement mechanisms to update keys without disrupting service.
• Timestamp and Nonce in Signed Requests: Include a timestamp and a unique nonce (number used once) in your signed requests. The timestamp helps protect against replay attacks by ensuring that a request is only valid for a limited time window. A nonce prevents the same request from being processed multiple times.
• HTTPS/TLS Usage: Always use HTTPS (TLS) for all API communications. This encrypts data in transit, protecting API keys, request payloads, and response data from eavesdropping and man-in-the-middle attacks. All Mossland API endpoints should enforce HTTPS.
• Input Validation: Implement robust input validation on all data submitted to the API. This can prevent various security vulnerabilities, including injection attacks, and ensures that your requests conform to API specifications.
• Error Handling: Implement secure error handling that avoids leaking sensitive information (e.g., internal server details, stack traces) in error responses. Provide generic error messages to clients and log detailed errors internally for debugging.
• Monitor API Usage: Regularly monitor your API usage logs for unusual activity, failed authentication attempts, or spikes in requests that could indicate a security incident.
• Stay Updated: Keep up-to-date with the latest security recommendations and API documentation from Mossland. Security threats evolve, and staying informed is crucial for maintaining a secure integration.