{"_id":"5c1d2323f0fb43004bbda824","project":"550f74bb6fc8130d0038aad3","version":{"_id":"550f75de61d9d30d00af9e01","__v":17,"project":"550f74bb6fc8130d0038aad3","forked_from":"550f74bb6fc8130d0038aad6","createdAt":"2015-03-23T02:09:34.221Z","releaseDate":"2015-03-23T02:09:34.221Z","categories":["550f75de61d9d30d00af9e02","551027e38579861900a86698","551029e08579861900a8669a","551029e7498062190006328a","5bc633a722d682005c9ad9e4","5bc633b08c4b0b000d6a7eaa","5bc633b48f3ff600626e3e18","5bc63538e5a6ba000d22ee6d","5bc63587a18a6b000decd295","5bc635c0937fcb0056223d9c","5bc6360f42f41800319aeaa6","5be5d13ff1d319002baca9ce","5be5d2287cd14d00291fbfdb","5be8b3b09f7cb70023c56a39","5be8b3cbb910100044e20206","5c1d769a4f6aed001fe527f0","5c402942010f0d001496dded"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"category":{"_id":"5be5d13ff1d319002baca9ce","project":"550f74bb6fc8130d0038aad3","version":"550f75de61d9d30d00af9e01","__v":0,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2018-11-09T18:26:07.698Z","from_sync":false,"order":0,"slug":"getting-started","title":"Wyre API"},"user":"54eb8076867e1917009b7160","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-12-21T17:30:11.860Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"apiSetting":null,"auth":"required","params":[],"url":""},"isReference":true,"order":3,"body":"[block:api-header]\n{\n  \"title\": \"Overview\"\n}\n[/block]\nWyre supports a set of authentication/authorization schemas to enable you to securely deliver your API payloads. The best choice depends on the type of integration you're attempting. Here's a breakdown of the different profiles of integrations and which portion of the API they should pay attention to:\n\nThe standard **centralized** authorization approach is used when you execute an API request directly to Wyre from a system under your control. This is the most-common approach. The safety of managed funds depends on the safety of your API credentials (you wouldn't distribute these credentials to customer devices, for example).\n\nIf you are using the accounts API to manage accounts for other people, you will need to use [masquerading](#masquerading) to control access.\n\n**Decentralized** applications use an auth system where end-users maintain their own credentials. This might be via browser, wallet software, or your own end-user application. Your servers (if you even have them) do not have access to the customer's keys or Wyre account.\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Secret Key Signature\",\n    \"1-0\": \"Token\",\n    \"2-0\": \"Password\",\n    \"3-0\": \"Keypair Signature\",\n    \"0-1\": \"Using an API key and a secret to sign requests. [details](#secret-key-signature-auth)\\n\\n(this is traditional API key authentication)\",\n    \"3-1\": \"_API Documentation In-Progress_\\n\\nThis is behind the scenes for the `web3` authentication built into the [Widget](doc:widget-getting-started)\",\n    \"2-1\": \"_Not available via the API, this is used for Wyre dashboard logins_\",\n    \"1-1\": \"Bearer token used for authentication [details](#token-auth)\",\n    \"h-0\": \"Auth Type\",\n    \"h-1\": \"Details\",\n    \"4-1\": \"\",\n    \"4-0\": \"\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Masquerading\"\n}\n[/block]\nIf you are using the accounts API to manage balances and/or KYC data on behalf of the actual account holders, you'll use your own Wyre account credentials and additionally supplying the query parameter `masqueradeAs`. This will cause the request to be performed on behalf of specified person. This helps to safeguard against both accidental and malicious access abuse.\n\nMasqueradeAs only applies to you if you are a business that is able to legally act on behalf of your customer for custodial type accounts.\n\nUnlike most API parameters, the `masqueradeAs` header **must** be passed as a query parameter in the API. If you are using API key signature auth, be sure to include this while signing.\n\nFor example, in order to get the account information for an account that you created with the ID `AC-XXXXXXX`, perform the following GET request:\n\n`GET https://api.sendwyre.com/v3/accounts/AC-XXXXXXX?masqueradeAs=AC-XXXXXXX`\n\n(along with your own credentials, whichever scheme you are using)\n\nBoth accounts (AC-XXXXXXX) in the url above are the same accounts. They should be the child account you are trying to masquerade as. The way we determine the parent account is through the API/Secret keys associated with the parent account.\n[block:api-header]\n{\n  \"title\": \"Secret Key Signature Auth\"\n}\n[/block]\nThis type of authentication involves using an API key to perform a signature of the request you're attempting to make.\n\nThe following table describes the headers you'll need to supply when performing your request:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HTTP Header\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"Your Wyre API key. Your key can be found at https://dash.sendwyre.com/settings/api-keys\",\n    \"0-0\": \"`X-Api-Key`\",\n    \"1-0\": \"`X-Api-Signature`\",\n    \"1-1\": \"A signature used to verify the request was sent by the account holder. See [Calculating the request signature](#section-calculating-the-request-signature).\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\nAdditionally, you should include a GET parameter named `timestamp` which is the current time in millisecond epoch format. We use this timestamp to help protect against replay attacks.\n\n## Calculating the request signature\n\nCalculating the `X-Api-Signature` field is a two step process:\n\n1.  Concatenate the request URL with the body of the HTTP request (encoded using UTF8) into a string. Use an empty string for the HTTP body in GET requests\n1.  Compute the signature as a HEX encoded HMAC with SHA-256 and your API Secret Key\n\n**Note:** You must send the request body exactly as you sign it, whitespace and all. The server calculates the signature based on exactly what's in the request body.\n[block:api-header]\n{\n  \"title\": \"Token Auth\"\n}\n[/block]\nFor this mechanism, a client-generated _bearer token_ is presented to the server on every request. This is a long, random string which acts as a long-lived session token, granting its bearer access. First, submit the key to the auth endpoint to initializes the key. This ensures its validity for subsequent use:\n\n`POST /v2/sessions/auth/key?secretKey=X`\n\nSee the [endpoint reference](doc:initialize-auth-token) for more details. Be **very certain** to use a cryptographically secure random number generator when creating this key, unless you know what you're doing. Remember that seeding it from (or hashing) any predictable source binds the token's security to the secrecy of the source.\n\nA simple curl example can be found [here](https://gist.github.com/nickolasteixeira/fb7b55c74e58dfabc1efdbc5159756a8).\n\nThe response contains an API Key which corresponds to the newly created credentials. This is helpful for managing the newly formed device connection (e.g. disconnecting the key from the account later, if necessary). The newly created session is valid, but has no corresponding account created.\n\nAfter the auth response is received, you may now use this token (secret key) to perform API requests. Supply it  to the API as a bearer token via the HTTP `Authorization` header:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HTTP Header\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`Authorization`\",\n    \"0-1\": \"The bearer token _aka secret key_. Make sure to include the string `Bearer ` (followed by a space) before the secret token:\\n\\n`Bearer XXX` \\n\\n(replacing `XXX` with the secret key)\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n### Next Steps\n\nThe first request after completing the auth token submission will typically be to [create a new account](doc:create-account). Make sure you supply the submitted bearer token when you hit this endpoint. After the account is created, the bearer token will now be associated with it. The rest of the API will now be available to it (and attempting account creation again with it will fail). \n\n### Additional Notes\n\nPresently, tokens can be also used as the secret key for [secret key signature auth](#secret-key-signature-auth) requests. This provides slightly more security, as the token itself is not transmitted again after the initial transmission to you. You'll need to use the API key returned from the `POST /v2/sessions/auth/key` call for this.","excerpt":"","slug":"authentication","type":"basic","title":"Authentication"}
[block:api-header] { "title": "Overview" } [/block] Wyre supports a set of authentication/authorization schemas to enable you to securely deliver your API payloads. The best choice depends on the type of integration you're attempting. Here's a breakdown of the different profiles of integrations and which portion of the API they should pay attention to: The standard **centralized** authorization approach is used when you execute an API request directly to Wyre from a system under your control. This is the most-common approach. The safety of managed funds depends on the safety of your API credentials (you wouldn't distribute these credentials to customer devices, for example). If you are using the accounts API to manage accounts for other people, you will need to use [masquerading](#masquerading) to control access. **Decentralized** applications use an auth system where end-users maintain their own credentials. This might be via browser, wallet software, or your own end-user application. Your servers (if you even have them) do not have access to the customer's keys or Wyre account. [block:parameters] { "data": { "0-0": "Secret Key Signature", "1-0": "Token", "2-0": "Password", "3-0": "Keypair Signature", "0-1": "Using an API key and a secret to sign requests. [details](#secret-key-signature-auth)\n\n(this is traditional API key authentication)", "3-1": "_API Documentation In-Progress_\n\nThis is behind the scenes for the `web3` authentication built into the [Widget](doc:widget-getting-started)", "2-1": "_Not available via the API, this is used for Wyre dashboard logins_", "1-1": "Bearer token used for authentication [details](#token-auth)", "h-0": "Auth Type", "h-1": "Details", "4-1": "", "4-0": "" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "title": "Masquerading" } [/block] If you are using the accounts API to manage balances and/or KYC data on behalf of the actual account holders, you'll use your own Wyre account credentials and additionally supplying the query parameter `masqueradeAs`. This will cause the request to be performed on behalf of specified person. This helps to safeguard against both accidental and malicious access abuse. MasqueradeAs only applies to you if you are a business that is able to legally act on behalf of your customer for custodial type accounts. Unlike most API parameters, the `masqueradeAs` header **must** be passed as a query parameter in the API. If you are using API key signature auth, be sure to include this while signing. For example, in order to get the account information for an account that you created with the ID `AC-XXXXXXX`, perform the following GET request: `GET https://api.sendwyre.com/v3/accounts/AC-XXXXXXX?masqueradeAs=AC-XXXXXXX` (along with your own credentials, whichever scheme you are using) Both accounts (AC-XXXXXXX) in the url above are the same accounts. They should be the child account you are trying to masquerade as. The way we determine the parent account is through the API/Secret keys associated with the parent account. [block:api-header] { "title": "Secret Key Signature Auth" } [/block] This type of authentication involves using an API key to perform a signature of the request you're attempting to make. The following table describes the headers you'll need to supply when performing your request: [block:parameters] { "data": { "h-0": "HTTP Header", "h-1": "Description", "0-1": "Your Wyre API key. Your key can be found at https://dash.sendwyre.com/settings/api-keys", "0-0": "`X-Api-Key`", "1-0": "`X-Api-Signature`", "1-1": "A signature used to verify the request was sent by the account holder. See [Calculating the request signature](#section-calculating-the-request-signature)." }, "cols": 2, "rows": 2 } [/block] Additionally, you should include a GET parameter named `timestamp` which is the current time in millisecond epoch format. We use this timestamp to help protect against replay attacks. ## Calculating the request signature Calculating the `X-Api-Signature` field is a two step process: 1. Concatenate the request URL with the body of the HTTP request (encoded using UTF8) into a string. Use an empty string for the HTTP body in GET requests 1. Compute the signature as a HEX encoded HMAC with SHA-256 and your API Secret Key **Note:** You must send the request body exactly as you sign it, whitespace and all. The server calculates the signature based on exactly what's in the request body. [block:api-header] { "title": "Token Auth" } [/block] For this mechanism, a client-generated _bearer token_ is presented to the server on every request. This is a long, random string which acts as a long-lived session token, granting its bearer access. First, submit the key to the auth endpoint to initializes the key. This ensures its validity for subsequent use: `POST /v2/sessions/auth/key?secretKey=X` See the [endpoint reference](doc:initialize-auth-token) for more details. Be **very certain** to use a cryptographically secure random number generator when creating this key, unless you know what you're doing. Remember that seeding it from (or hashing) any predictable source binds the token's security to the secrecy of the source. A simple curl example can be found [here](https://gist.github.com/nickolasteixeira/fb7b55c74e58dfabc1efdbc5159756a8). The response contains an API Key which corresponds to the newly created credentials. This is helpful for managing the newly formed device connection (e.g. disconnecting the key from the account later, if necessary). The newly created session is valid, but has no corresponding account created. After the auth response is received, you may now use this token (secret key) to perform API requests. Supply it to the API as a bearer token via the HTTP `Authorization` header: [block:parameters] { "data": { "h-0": "HTTP Header", "h-1": "Description", "0-0": "`Authorization`", "0-1": "The bearer token _aka secret key_. Make sure to include the string `Bearer ` (followed by a space) before the secret token:\n\n`Bearer XXX` \n\n(replacing `XXX` with the secret key)" }, "cols": 2, "rows": 1 } [/block] ### Next Steps The first request after completing the auth token submission will typically be to [create a new account](doc:create-account). Make sure you supply the submitted bearer token when you hit this endpoint. After the account is created, the bearer token will now be associated with it. The rest of the API will now be available to it (and attempting account creation again with it will fail). ### Additional Notes Presently, tokens can be also used as the secret key for [secret key signature auth](#secret-key-signature-auth) requests. This provides slightly more security, as the token itself is not transmitted again after the initial transmission to you. You'll need to use the API key returned from the `POST /v2/sessions/auth/key` call for this.