Generating M2M API Keys (Live vs. Test Environments)

To programmatically integrate Nyota Imara services—such as automated identity verification (Nyota ID), transactional SMS dispatch (Nyota SMS), or S3 cloud storage (Nyota Drive)—your application must authenticate using Machine-to-Machine (M2M) API keys.

This guide explains how API keys are secured under the hood, the critical differences between Live and Test environments, how to generate and rotate keys, and how to resolve authentication errors.

1. How API Keys Work Under the Hood

Nyota Imara enforces an enterprise-grade cryptographic security architecture for all developer credentials:

1. KEY GENERATION (Developer Dashboard)
    Admin selects environment (Live / Test) -> Assigns permission scopes
    -> System generates cryptographically random token:
       ny_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                         │
                         ▼
 2. ONE-TIME SECRET DISPLAY & SHA-256 HASHING
    - Plaintext key is displayed ONCE on screen for the user to copy.
    - System computes non-reversible SHA-256 hash:
      hash = sha256(ny_live_...) -> Stores ONLY the hash in verify.api_keys.
                         │
                         ▼
 3. REQUEST AUTHENTICATION (x-nyota-api-key)
    Client backend sends header: x-nyota-api-key: ny_live_...
    -> Nyota Gateway computes sha256(incomingKey) -> Matches stored hash
    -> Evaluates workspace PBAC permission scopes.

The One-Time Display Security Rule

Nyota Imara never stores your raw API key in plaintext. We store only non-reversible SHA-256 hashes. Because of this security measure, we cannot view, retrieve, or restore a lost API key. If you lose a secret key, you must revoke it and generate a new one.

2. Environment Comparison: Live vs. Test Mode

3. Step-by-Step: How to Generate an API Key

1. Log in to accounts.nyotaimara.com and ensure your Business Workspace is selected.
2. In the left navigation sidebar, click Identity API & Keys (/identity-api).
3. Click the "Generate New API Key" button in the top right.
4. Provide a descriptive label (e.g., Production Backend - Next.js or Staging Server).
5. Select the Environment:
6. • Live Mode: For production deployments.
   • Test Mode: For development and automated testing.
6. Select Permission Scopes:
7. • Choose * (Full Platform Access) or limit the key to specific services (e.g., sms:send, drive:file:write, id:session:create).
7. Click "Create API Key".
8. Copy your secret key immediately and save it to your server’s secure environment configuration (.env).

# Example Server Environment Variable (.env)
NYOTA_API_KEY="ny_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

4. Common Pitfalls & How to Troubleshoot

Pitfall A: "My API request returns 401 Unauthorized: Invalid API Key."

• The Cause: The API key header was omitted, misformatted, or revoked.
• The Resolution:
• • Ensure your HTTP request sends the key in the exact header:
    x-nyota-api-key: ny_live_... (or Authorization: Bearer ny_live_...).
  • Check for trailing spaces or line breaks copied into your .env file.

Pitfall B: "My API call returns 403 Forbidden: Missing required scope."

• The Cause: The API key was provisioned with restricted scopes that do not include the action you are attempting to execute (e.g., attempting an SMS broadcast with a key only permitted for id:verify).
• The Resolution:
• 1. Go to accounts.nyotaimara.com/identity-api.
  2. Check the active scopes for your key.
  3. Revoke the key and generate a new key with full permissions (*) or add the required scope.

Pitfall C: "I accidentally committed my API key to a public GitHub repository."

• The Cause: A developer pushed a .env file containing live credentials to a version control system.
• The Resolution (Immediate Action Required):
• 1. Log in to accounts.nyotaimara.com/identity-api immediately.
  2. Locate the exposed key and click "Revoke Key". This instantly invalidates the key across all global edge gateways.
  3. Generate a fresh API key and store it in your deployment environment variables (e.g., Vercel, AWS Secrets Manager, GitHub Secrets).

5. Security Best Practice: Server-Side Isolation

Master API keys (ny_live_...) hold full financial and programmatic access to your workspace resources.

Never expose master API keys in client-side code, frontend React components, or compiled mobile apps.

• Web Frontends: Make requests to your own backend server, which then calls Nyota APIs using your secret key.
• Identity Verification (ID): Call POST /v1/verify/sessions from your backend to generate short-lived, single-use session tokens for client SDKs.

Related Support Guides & Links

• Managing Financial Shield Limits & Budget Caps
• Validating B2B HMAC Webhook Signatures
• Direct API Key Console