Authentication

All API endpoints require authentication using an API Key. You need to include your API key in the request header.

Getting Your API Key

1. Log into your 1Money dashboard
2. Navigate to API Settings
3. Generate or copy your API key
4. Keep your API key secure and never share it publicly

Sandbox：Bearer Token Authentication

In sandbox mode, OneMoney uses a simpler Bearer token scheme instead of HMAC signatures.

Authorization: Bearer <ACCESS_KEY>

• In this mode:
  • You do not need to compute BODY_HASH, STRING_TO_SIGN, or SIGNATURE.
  • Only the Authorization header is required;

Example using cURL in sandbox mode:

curl -X GET \
  -H "Authorization: Bearer your_sandbox_access_key" \
  "https://api.sandbox.1money.com/api/v1/customers"

Production：HMAC Authentication

Given:

• ACCESS_KEY – your access key ID
• SECRET_KEY – your secret key
• METHOD – HTTP method (e.g. POST)
• PATH – URI path (e.g. /api/v1/customers, without query string)
• BODY – request body bytes (may be empty; e.g. "" for GET)

1. Generate timestamp

• Use current UTC time in YYYYMMDDTHHMMSSZ.
• Example: 20250115T123045Z.

2. Compute body hash

• Compute BODY_HASH = sha256_hex(BODY), lowercase hex, 64 chars.
• For an empty body (BODY = ""), this is the SHA-256 of the empty string.

3. Build canonical string

STRING_TO_SIGN =
<ACCESS_KEY>\n
<TIMESTAMP>\n
<METHOD_UPPER>\n
<PATH>\n
<BODY_HASH>

Example:

my-access-key
20250115T123045Z
POST
/api/v1/customers
0d2c3...fabc   # (actual 64-char SHA-256 hex)

Notes:

• METHOD_UPPER is the HTTP method uppercased (e.g. get → GET).
• PATH is the request path only (e.g. /api/v1/customers), do not include base URL or query string.
• Query parameters are not part of the string to sign.

4. Compute signature

1. Decode SECRET_KEY from Base64 URL-safe to bytes.
2. Compute HMAC_SHA256(SECRET_KEY_BYTES, STRING_TO_SIGN).
3. Hex encode the result (lowercase) → <SIGNATURE> (64 hex chars).

5. Build headers

• Authorization:

  Text

  OneMoney-HMAC-SHA256 <ACCESS_KEY>:<TIMESTAMP>:<SIGNATURE>

• X-OM-Date:

  Text

  X-OM-Date: <TIMESTAMP>

  TIMESTAMP must be exactly the same value used in STRING_TO_SIGN.

• Content-Type:

  • For JSON requests with a body: Content-Type: application/json.
  • For requests without a body, Content-Type may be omitted.

6. Send the HTTP request

• Use the exact METHOD, PATH, and BODY you used for signing.
• Include both Authorization and X-OM-Date headers.
• If you add query parameters, they go in the URL only (they are not signed).

7. Shell / cURL Example

Below is a self-contained example using common Unix tools.

#!/usr/bin/env bash
set -euo pipefail

# 1. Configuration
ACCESS_KEY="your_access_key"
SECRET_KEY="your_base64_url_safe_secret"   # Base64 URL-safe, no padding (-_/)
METHOD="POST"
REQUEST_PATH="/api/v1/customers"
BODY='{"name":"John Doe","email":"[email protected]"}'
BASE_URL="https://api.example.com"

# 2. Timestamp (UTC, format: YYYYMMDDThhmmssZ)
TIMESTAMP=$(date -u +"%Y%m%dT%H%M%SZ")

# 3. Body hash (SHA-256, hex lowercase)
BODY_HASH=$(printf '%s' "$BODY" | shasum -a 256 | awk '{print $1}')

# 4. Canonical string to sign
STRING_TO_SIGN=$(printf "%s\n%s\n%s\n%s\n%s" \
  "$ACCESS_KEY" "$TIMESTAMP" "$(printf '%s' "$METHOD" | tr '[:lower:]' '[:upper:]')" \
  "$REQUEST_PATH" "$BODY_HASH")

# 5. Decode secret key from Base64 URL-safe and compute HMAC-SHA256
# Convert URL-safe Base64 (-_) to standard (+/), then decode.
HEX_KEY=$(
  printf '%s' "$SECRET_KEY" \
    | tr '-_' '+/' \
    | base64 -d \
    | xxd -p -c 256
)

SIGNATURE=$(printf '%s' "$STRING_TO_SIGN" \
  | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$HEX_KEY" \
  | awk '{print $2}')

# 6. Headers
AUTH_HEADER="OneMoney-HMAC-SHA256 $ACCESS_KEY:$TIMESTAMP:$SIGNATURE"
DATE_HEADER="$TIMESTAMP"

# 7. Example request
curl -X "$METHOD" \
  -H "Authorization: $AUTH_HEADER" \
  -H "X-OM-Date: $DATE_HEADER" \
  -H "Content-Type: application/json" \
  -d "$BODY" \
  "$BASE_URL$REQUEST_PATH"

8. Error Responses

• 401 Unauthorized: Missing or invalid API key
  • JSON

    {
      "status_code": 401,
      "code": "Unauthorized",
      "instance": "/v1/customers/tos_links",
      "detail": "Credential not found XXXXXX"
    }

    Invalid secret key
  • JSON

    {
      "status_code": 401,
      "code": "Unauthorized",
      "instance": "/v1/customers/tos_links",
      "detail": "Signature verification failed: Signature verification failed: Signature mismatch"
    }