Authentication

You'll need to authenticate your requests to access any of the endpoints in the MayaRamp API. In this guide, we'll look at how authentication works. MayaRamp offers two ways to authenticate your API requests: Using HTTP Signature Authentication (For Personal Use).

API Base URLs:

Production: https://staging.mayaramp.com
Staging: https://staging.mayaramp.com (used in examples below)

Dashboard URLs:

Production: https://dashboard.mayaramp.com
Staging: https://dashboard-staging.mayaramp.com

HTTP Signature Authentication (Personal Token)

HTTP Signature Authentication is a method of signing HTTP requests to authenticate requests without sending the API key in the request. This means you don't need to interact with /auth endpoint since you already have a personal key generated through the dashboard

MayaRamp uses asymmetric key encryption to sign requests. The client will generate a signature using their private key and MayaRamp will use the client's public key to validate the signature.

You need provide signature with client ID and timeStamp in the header of your request. for example:

  curl "https://staging.mayaramp.com/v1/user/me" \
  -H "X-SIGNATURE: YOUR_SIGNATURE" \
  -H "X-TIMESTAMP: TIMESTAMP" \
  -H "X-CLIENT-ID: YOUR_CLIENT_ID"

X-SIGNATURE = Your generated signature
X-TIMESTAMP = format with YYYY-MM-DDTHH:mm:ssZ
X-CLIENT-ID = Your client ID from MayaRamp

The following steps will explain about Asymmetric key usage without Access Token (SHA256withRSA).

Generate Private and Public Key

As the new version, you can generate the keys directly from MayaRamp Dashboard under API keys section

which is where rsa_private_key.pem is obtained from MayaRamp

Digital Signature Generation

Compose the string to sign with format by method:
- POST, PATCH, PUT = $CLIENT-ID + “:“ + $X-TIMESTAMP + “:“ + LowerCase(HexEncode(SHA-256(Minify($BODY))))
- GET, DELETE = $CLIENT-ID + “:“ + $X-TIMESTAMP
$CLIENT-ID is String, $BODY is JSON format, $X-TIMESTAMP timestamp format with YYYY-MM-DDTHH:mm:ssZ
The signature string is generated from string to sign above with applying SHA-256 with RSA-2048 encryption using pkcs8 private key, and then encode the result to base64.
Put the signature string into HTTP header “ X-SIGNATURE“.

Example:

X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5

NOTES : You do not need the Bearer token using this personal token since you have been authenticated using the signature

Example Generate signature using nodejs

const crypto = require('crypto')

const generateAssymetricSignature = ({ body, timeStamp, method, clientID, privateKey }) => {
  const myPemKey = privateKey

  // Asymmetric Key Generation

  // Minify the HTTP body
  const minfiedBodyEncrypted = JSON.stringify(body || {})

  // Create a SHA-256 hash object
  const hash = crypto.createHash('sha256')

  // Add the data to the hash object
  hash.update(minfiedBodyEncrypted)

  // Calculate the SHA-256 hash
  const hexSHA = hash.digest('hex')
  const minfiedBodyEncryptedLower = hexSHA.toLowerCase()

  // Generate the string to be signed
  let stringToSign = ''

  // POST, PATCH, PUT = <X-CLIENT-ID> + “:“ + <X-TIMESTAMP> + “:“ + LowerCase(HexEncode(SHA-256(Minify(<HTTP BODY>))))
  // GET, DELETE = <X-CLIENT-ID> + “:“ + <X-TIMESTAMP>

  switch (method) {
    case 'GET':
      stringToSign = `${clientID}:${timeStamp}`
      break
    case 'DELETE':
      stringToSign = `${clientID}:${timeStamp}`
      break
    case 'POST':
      stringToSign = `${clientID}:${timeStamp}:${minfiedBodyEncryptedLower}`
      break
    case 'PATCH':
      stringToSign = `${clientID}:${timeStamp}:${minfiedBodyEncryptedLower}`
      break
    case 'PUT':
      stringToSign = `${clientID}:${timeStamp}:${minfiedBodyEncryptedLower}`
      break
    default:
      stringToSign = ''
      break
  }

  // Throw error if stringToSign is empty
  if (!stringToSign) throw 'method not allowed'

  // Create a signer object
  const sign = crypto.createSign('SHA256')

  // Update the signer object with the data to be signed
  sign.update(stringToSign)

  // Sign the data
  const signature = sign.sign(myPemKey, 'hex')

  // Encode the signature to base64
  const base64Signature = Buffer.from(signature, 'hex').toString('base64')

  return console.log(base64Signature)
}

generateAssymetricSignature({
  body: { message: 'John Doe' },
  timeStamp: '2021-01-01T00:00:00Z',
  method: 'POST',
  clientID: '<YOUR_CLIENT_ID>',
  privateKey: '<YOUR_PRIVATE_KEY>'
})

Then you can hit the endpoint /test/verify-signin to verify whether the signature is valid or not.

Generate Your Signature

Private KeyClient iDBody (JSON)MethodDate - Automatically Generated