Authentication

Overview

The NOAH Business API uses both an API Key and Request Signing to authenticate requests, ensuring secure communication between your system and our API.

Keys

There are three important security keys required to work with NOAH's API:

Name	Description
API Key	Used to identify and authenticate your requests.
Request Signing Private Key	Used by your system to sign requests. Never share this key.
Request Signing Public Key	Used when creating API Keys and later by our API for request signature verification.

Headers

Every request to our API must include the following headers:

Header	Description
X-Api-Key	Contains your API Key created in the NOAH Dashboard.
Api-Signature	Contains a JWT (JSON Web Token) with claims related to your request, signed using your Request Signing Private Key.

More information about request signing can be found here.

Security of your Funds

Never send us nor share your Request Signing Private Key. It should be securely stored in your system and never exposed publicly.

API Keys

API Keys are generated and managed through the NOAH Business Dashboard. They provide full access to our APIs for initiating financial operations, thus requiring stringent security measures. Remember:

• Never expose your API Keys in client-side code, public repositories like GitHub, or transfer them over unencrypted networks.
• Avoid internal broadcasting within your organization. Share API Keys only with authorized personnel.
• Secure Storage: The API Key is only visible at the time of creation and cannot be retrieved later. Ensure it is stored securely in your own systems.
• Regular Rotation: Rotate your API Keys periodically to minimize security risks.

Key Format

API Keys follow the format: <type>_<env>_<key>

• type: Currently apikey (more types coming soon)
• env: sandbox | prod
• key: A randomly generated string unique to your API Key

Example: apikey_prod_12345abcdef

Request Signing

More information about request signing can be found here.

Error Handling

A 401 Unauthorized HTTP status code will be returned in the following scenarios:

• Missing Credentials:
  • Requests made over plain HTTP.
  • Requests with missing X-Api-Key header.
• Invalid Credentials:
  • Requests with invalid or expired API Keys.
  • Requests with invalid or expired signed JWTs.
• Environment Mismatch:
  • Requests made using an API Key with a mismatched env value.
• Signature Issues:
  • Requests in prod with missing Api-Signature header.
  • Requests in sandbox with missing Api-Signature header when using an API Key associated with a Request Signing Public Key.
• Unauthorized Access:
  • Requests made from a browser using the X-Api-Key header.

Coming Soon

• Scoped API Keys: For granular permissions and enhanced security control.

---

Generate Your API Key

1. Onboard with NOAH

   • Register your interest via the NOAH Business First Contact Form.
   • You may integrate with our prod environment once our team has completed the necessary KYB and AML checks.
   • For more information, visit Onboarding.
   • Note: While your KYB and AML checks are in progress, a NOAH Representative will invite you to integrate with our Sandbox Environment.

2. Register Your NOAH Account

   • Through the sandbox Dashboard.
   • Note: In Beta mode, this will create a personal NOAH account. Contact your NOAH Onboarding representative to upgrade to a Business account.

3. Upgrade to a Business Account

   • Once upgraded, log in to the sandbox Environment to access your NOAH Dashboard.

4. Navigate to API Key Configuration

   • Select "Configuration" from the sidebar.
   • You will see an empty list of "Active API Keys."

5. Create a New API Key

   • Click on "Create New Key."

6. Configure Your API Key

   • Label: Enter a memorable label for your new API Key.
   • Expiry Date (Optional): Set an expiration date for the key.
   • Request Signing Public Key: Enter your in PEM format. If you need to generate a new key pair, please refer to Key Generation.

7. Finalize Key Creation

   • Click "Add."
   • Your new API Key will be displayed once. Securely store it immediately as it cannot be retrieved later.

8. Secure Your API Key

   • Store the API Key in a secure location and avoid sharing it.
   • We only store a hash of your generated API Key, making it irretrievable through our system.

9. Include API Key in Requests

   • Add your API Key to the X-Api-Key header of all API requests.

10. Manage Existing API Keys

    • Existing API Keys can be removed via the Business Dashboard, which will revoke access for the removed key.

Request Signing in Sandbox Environment

To facilitate easier testing with manual tools such as Postman, it is possible in our sandbox environment to create an API Key without a Request Signing Public Key, allowing unsigned requests. However, before graduation to prod, we require that at least one API Key is created with an associated Request Signing Public Key so that we can verify your system is correctly signing requests.