Authentication & Key Management

Overview

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 (see below) 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.

Auth Type	Details
Secret Key Signature	Using an API key and a secret to sign requests. details (this is traditional API key authentication)
Token	Bearer token used for authentication details
Password	Not available via the API, this is used for Wyre dashboard logins

Masquerading

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)

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.

Secret Key Signature Auth

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:

HTTP Header	Description
X-Api-Key	Your Wyre API key. Your key can be found at https://dash.sendwyre.com/settings/api-keys
X-Api-Signature	A signature used to verify the request was sent by the account holder. See below for more details.

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

2. 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.

Token Auth

For this mechanism, a client-generated bearer token is presented to the server on every request. This is a long, random string that 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 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.

The response contains an API Key that 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:

HTTP Header	Description
Authorization	The bearer token aka secret key. Make sure to include the string Bearer (followed by a space) before the secret token: Bearer XXX (replacing XXX with the secret key)

Next Steps

The first request after completing the auth token submission will typically be to create a new 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 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.