Authentication Guide

The mCards API supports two authentication methods: HMAC-SHA256 signatures for server-to-server integrations, and OAuth2 Bearer tokens for client applications with scoped access.

HMAC-SHA256 Authentication

HMAC authentication signs every request with your API secret, ensuring message integrity and authenticity.

How It Works

Serialize the request body as JSON (use "" for GET requests with no body)
Compute HMAC-SHA256 of the body using your API secret
Base64-encode the signature
Send the header: Authorization: HMAC_SHA256 {api_key};{base64_signature}

Signature Format

text

Authorization: HMAC_SHA256 {api_key};{base64(hmac_sha256(request_body, api_secret))}

TypeScript Example

typescript

import { McardsSdk } from '@mcards/sdk';

const client = new McardsSdk({
  apiKey: process.env.MCARDS_API_KEY,
  apiSecret: process.env.MCARDS_API_SECRET,
  baseUrl: 'https://api.mcards.com',
});

// All requests are automatically signed
const { data: profile } = await client.partner.getProfile();

Python Example

python

import os
from mcards_sdk import McardsSdk

client = McardsSdk(
    api_key=os.environ["MCARDS_API_KEY"],
    api_secret=os.environ["MCARDS_API_SECRET"],
    base_url="https://api.mcards.com",
)

# All requests are automatically signed
profile = client.partner.get_profile()

Manual Signature (cURL)

bash

API_KEY="your-api-key"
API_SECRET="your-api-secret"
BODY='""'

SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X GET https://api.mcards.com/api/v2/partner/profile \
  -H "Authorization: HMAC_SHA256 ${API_KEY};${SIGNATURE}" \
  -H "Content-Type: application/json"

Signing Rules

Request Type	Body to Sign
GET (no body)	`""` (empty string with quotes)
POST/PUT with JSON	The full JSON body string
POST form-encoded	The form body string

Important: The signature is computed over the exact byte string of the body. Whitespace differences will produce different signatures.

OAuth2 Bearer Token Authentication

OAuth2 uses the client credentials grant to exchange a client ID and secret for a time-limited access token.

Step 1: Create an OAuth Application

bash

curl -X POST https://api.mcards.com/api/v2/oauth/applications \
  -H "Authorization: HMAC_SHA256 ${API_KEY};${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "scopes": "partner:read wallets:read cards:read"}'

Step 2: Exchange for Access Token

bash

curl -X POST https://api.mcards.com/api/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=mcp_abc123&client_secret=secret_xyz789"

Step 3: Use the Token

bash

curl https://api.mcards.com/api/v2/partner/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

Token Lifecycle

Operation	Endpoint	Auth Required
Create token	`POST /api/v2/oauth/token`	None (client credentials in body)
Introspect token	`GET /api/v2/oauth/token_info`	Bearer token
Revoke token	`POST /api/v2/oauth/revoke`	HMAC or Bearer
List apps	`GET /api/v2/oauth/applications`	HMAC or Bearer

Token Expiry

Access tokens expire after 1 hour (3600 seconds)
The expires_in field indicates seconds until expiry
Request a new token when the current one expires — there is no refresh token flow

API Scopes

Scopes control what resources a Bearer token can access. HMAC authentication has full access.

Available Scopes

Scope	Description
`partner:read`	Read partner profile, keys, roles
`partner:write`	Update partner settings
`wallets:read`	List and view wallets
`wallets:write`	Create and update wallets
`cards:read`	List and view cards, balances
`cards:write`	Issue, activate, deactivate cards
`transactions:read`	List and view transactions
`cardholders:read`	List and view cardholders
`cardholders:write`	Create and update cardholders
`programs:read`	List and view programs
`rewards:read`	List and view rewards
`rewards:write`	Create and manage rewards
`offers:read`	List and view offers
`offers:write`	Create and manage offers
`webhooks:read`	List and view webhooks
`webhooks:write`	Create, update, delete webhooks
`payments:read`	List payment gateways and accounts
`branding:read`	View card designs
`analytics:read`	View analytics and metrics
`sandbox:read`	Read sandbox environment info
`sandbox:write`	Execute sandbox simulations

Shorthand Scopes

Shorthand	Expands To
`read`	All read scopes
`write`	All write scopes
`admin`	All scopes

Security Best Practices

Never expose API secrets in client-side code — use HMAC only in server environments
Use OAuth2 with minimal scopes for client-facing applications
Rotate secrets periodically via the partner dashboard
Store credentials in environment variables, never in source code
Use HTTPS exclusively — the API rejects plaintext HTTP requests
Monitor rate limits via X-RateLimit-* response headers