{"_id":"56326ea3df556c0d00cd08f7","category":{"_id":"56326e9ddf556c0d00cd08cc","__v":1,"project":"544fc17e698ab40800b4f891","version":"56326e9cdf556c0d00cd08ca","pages":["56326ea3df556c0d00cd08f6","56326ea3df556c0d00cd08f7","56326ea3df556c0d00cd08f8"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-05-01T05:42:46.293Z","from_sync":false,"order":1,"slug":"authentication","title":"Authentication"},"user":"544fc065698ab40800b4f888","project":"544fc17e698ab40800b4f891","parentDoc":null,"__v":1,"version":{"_id":"56326e9cdf556c0d00cd08ca","project":"544fc17e698ab40800b4f891","__v":2,"createdAt":"2015-10-29T19:08:12.724Z","releaseDate":"2015-10-29T19:08:12.724Z","categories":["56326e9ddf556c0d00cd08cb","56326e9ddf556c0d00cd08cc","56326e9ddf556c0d00cd08cd","56326e9ddf556c0d00cd08ce","56326e9ddf556c0d00cd08cf","56326e9ddf556c0d00cd08d0","56326e9ddf556c0d00cd08d1","56326e9ddf556c0d00cd08d2","56326e9ddf556c0d00cd08d3","56326e9ddf556c0d00cd08d4","56d942ac337fd11300d6a251"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"collector","version_clean":"2.1.0","version":"2.1"},"updates":["5981c9d8302822002abfc7a6"],"next":{"pages":[],"description":""},"createdAt":"2015-05-01T07:58:38.852Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"# HMAC Authentication\n\nHMAC Authentication can be used for authentication through the coins.ph API using the application developer's account. \n\nIf you are building a client side application, we recommend using [OAuth2](doc:oauth) instead. This is because HMAC requires you to use your API secret to sign requests, which you should store in a medium that you control, such as your own server.\n\nYou can get your API Key and secret by selecting your application and clicking \"show\" from the [API Access Dashboard](https://coins.ph/user/api).\n\n## Signing a request\n\nEach request made with HMAC Authentication needs to be signed. The code below demonstrates how to sign a request.\n\nFor an example of how to use this function for an HMAC request, please see the [Send funds to an email/phone number](doc:send-funds-to-an-email-address-or-a-phone-number) tutorial.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"\\\"\\\"\\nhmac_example.py\\n\\nSign a request using an API_KEY and an API_SECRET.\\n\\\"\\\"\\\"\\nimport hashlib\\nimport hmac\\nimport time\\nimport json\\n\\nAPI_KEY = 'YOUR_API_KEY'  # Replace this with your API Key\\nAPI_SECRET = 'YOUR_API_SECRET'  # Replace this with your API secret\\n\\n\\ndef get_nonce():\\n    \\\"\\\"\\\"Return a nonce based on the current time.\\n  \\n    A nonce should only use once and should always be increasing.\\n    Using the current time is perfect for this.\\n    \\\"\\\"\\\"\\n    # Get the current unix epoch time, and convert it to milliseconds\\n \\t  return int(time.time() * 1e6)\\n\\n  \\ndef sign_request(url, nonce, body=None):\\n    \\\"\\\"\\\"Return an HMAC signature based on the request.\\\"\\\"\\\"\\n    if body is None:\\n        # GET requests don't have a body, so we'll skip that for signing\\n        message = str(nonce) + url\\n    else:\\n        body = json.dumps(body, separators=(',', ':'))\\n        message = str(nonce) + url + body\\n        \\n    return str(\\n        hmac.new(\\n            str(API_SECRET),\\n            message,\\n            hashlib.sha256\\n        ).hexdigest()\\n    )\\n\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"String nonce = String.valueOf(System.currentTimeMillis());\\nString message = nonce + url + (body != null ? body : \\\"\\\");\\n\\nMac mac = Mac.getInstance(\\\"HmacSHA256\\\");\\nmac.init(new SecretKeySpec(API_SECRET.getBytes(), \\\"HmacSHA256\\\"));\\nString signature = new String(Hex.encodeHex(mac.doFinal(message.getBytes())));\\nrequest.setHeader(\\\"ACCESS_KEY\\\", API_KEY);\\nrequest.setHeader(\\\"ACCESS_SIGNATURE\\\", signature);\\nrequest.setHeader(\\\"ACCESS_NONCE\\\", nonce);\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n\n## Making Requests\n\nEach HMAC requests expect the following HTTP Headers:\n\n* **ACCESS_KEY** - Select `show` on your chosen application's [API Access](https://coins.ph/user/api) dashboard. This is the API Key as displayed on the dialog.\n* **ACCESS_SIGNATURE** - An HMAC-SHA256 hash of the nonce concatenated with the full URL and body of the HTTP request, signed using your API secret.\n* **ACCESS_NONCE** - A number that can only be used once per user. See [Authentication](auth.html)\n\nAdditional headers may be required depending on the API call you are making. For instance, POST requests require the header `Content-Type: application/json`, while GET requests do not expect this header.\n\n## Use a Nonce\n\nA [nonce](http://en.wikipedia.org/wiki/Cryptographic_nonce) is used to prevent\nreplay-attacks. Every API call requires a nonce. We expect the nonce to always\nincrease for every request from the same user. The simplest form of nonce you\ncan use is a Unix Epoch timestamp, but feel free to use other forms.\n\n## Storing Credentials Securely\n\nAlways make sure your API Credentials are stored securely, Your `api_key`,\n`api_secret`, and access tokens may be used to access and perform actions in\nyour coins account. In particular, you should avoid storing credentials in your\ncode base and code repositories (like github).\n\nCoins will never ask for your API secret. There is no need to include the API\nsecret on a request.\n\nIf there's a need for you to store your secret in a device you don't control\n(say, a mobile device), it is completely your responsibility to protect the\nsecret. We recommend using encryption and using obfuscators to protect your\napplication from disassemblers and reverse-engineering. Please refer to your\nchosen platform's documentation for more information.","excerpt":"","slug":"hmac","type":"basic","title":"HMAC"}
# HMAC Authentication HMAC Authentication can be used for authentication through the coins.ph API using the application developer's account. If you are building a client side application, we recommend using [OAuth2](doc:oauth) instead. This is because HMAC requires you to use your API secret to sign requests, which you should store in a medium that you control, such as your own server. You can get your API Key and secret by selecting your application and clicking "show" from the [API Access Dashboard](https://coins.ph/user/api). ## Signing a request Each request made with HMAC Authentication needs to be signed. The code below demonstrates how to sign a request. For an example of how to use this function for an HMAC request, please see the [Send funds to an email/phone number](doc:send-funds-to-an-email-address-or-a-phone-number) tutorial. [block:code] { "codes": [ { "code": "\"\"\"\nhmac_example.py\n\nSign a request using an API_KEY and an API_SECRET.\n\"\"\"\nimport hashlib\nimport hmac\nimport time\nimport json\n\nAPI_KEY = 'YOUR_API_KEY' # Replace this with your API Key\nAPI_SECRET = 'YOUR_API_SECRET' # Replace this with your API secret\n\n\ndef get_nonce():\n \"\"\"Return a nonce based on the current time.\n \n A nonce should only use once and should always be increasing.\n Using the current time is perfect for this.\n \"\"\"\n # Get the current unix epoch time, and convert it to milliseconds\n \t return int(time.time() * 1e6)\n\n \ndef sign_request(url, nonce, body=None):\n \"\"\"Return an HMAC signature based on the request.\"\"\"\n if body is None:\n # GET requests don't have a body, so we'll skip that for signing\n message = str(nonce) + url\n else:\n body = json.dumps(body, separators=(',', ':'))\n message = str(nonce) + url + body\n \n return str(\n hmac.new(\n str(API_SECRET),\n message,\n hashlib.sha256\n ).hexdigest()\n )\n", "language": "python" }, { "code": "String nonce = String.valueOf(System.currentTimeMillis());\nString message = nonce + url + (body != null ? body : \"\");\n\nMac mac = Mac.getInstance(\"HmacSHA256\");\nmac.init(new SecretKeySpec(API_SECRET.getBytes(), \"HmacSHA256\"));\nString signature = new String(Hex.encodeHex(mac.doFinal(message.getBytes())));\nrequest.setHeader(\"ACCESS_KEY\", API_KEY);\nrequest.setHeader(\"ACCESS_SIGNATURE\", signature);\nrequest.setHeader(\"ACCESS_NONCE\", nonce);", "language": "java" } ] } [/block] ## Making Requests Each HMAC requests expect the following HTTP Headers: * **ACCESS_KEY** - Select `show` on your chosen application's [API Access](https://coins.ph/user/api) dashboard. This is the API Key as displayed on the dialog. * **ACCESS_SIGNATURE** - An HMAC-SHA256 hash of the nonce concatenated with the full URL and body of the HTTP request, signed using your API secret. * **ACCESS_NONCE** - A number that can only be used once per user. See [Authentication](auth.html) Additional headers may be required depending on the API call you are making. For instance, POST requests require the header `Content-Type: application/json`, while GET requests do not expect this header. ## Use a Nonce A [nonce](http://en.wikipedia.org/wiki/Cryptographic_nonce) is used to prevent replay-attacks. Every API call requires a nonce. We expect the nonce to always increase for every request from the same user. The simplest form of nonce you can use is a Unix Epoch timestamp, but feel free to use other forms. ## Storing Credentials Securely Always make sure your API Credentials are stored securely, Your `api_key`, `api_secret`, and access tokens may be used to access and perform actions in your coins account. In particular, you should avoid storing credentials in your code base and code repositories (like github). Coins will never ask for your API secret. There is no need to include the API secret on a request. If there's a need for you to store your secret in a device you don't control (say, a mobile device), it is completely your responsibility to protect the secret. We recommend using encryption and using obfuscators to protect your application from disassemblers and reverse-engineering. Please refer to your chosen platform's documentation for more information.