{"_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\": \"Keypair Signature\",\n    \"3-0\": \"Password\",\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\": \"_Not available via the API, this is used for Wyre dashboard logins_\",\n    \"2-1\": \"_API Documentation In-Progress_\\n\\nThis is behind the scenes for the `web3` authentication built into the [Widget](doc:widget-getting-started)\",\n    \"1-1\": \"Bearer token used for authentication [details](#token-auth)\",\n    \"h-0\": \"Auth Type\",\n    \"h-1\": \"Details\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\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\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[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\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 (assuming no account was already connected) 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": "Keypair Signature", "3-0": "Password", "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": "_Not available via the API, this is used for Wyre dashboard logins_", "2-1": "_API Documentation In-Progress_\n\nThis is behind the scenes for the `web3` authentication built into the [Widget](doc:widget-getting-started)", "1-1": "Bearer token used for authentication [details](#token-auth)", "h-0": "Auth Type", "h-1": "Details" }, "cols": 2, "rows": 4 } [/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. 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) [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. 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 (assuming no account was already connected) 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.