Home Integration and API API Authentication

API Authentication

Last updated on Nov 04, 2024

Before being able to sign any requests, you must create an API key from your profile page in the YaYa Wallet sandbox website.

Upon creating a key you need to have 2 pieces of information:

  • API Key

  • API Secret

The API Key and API Secret are generated and provided by YaYa Wallet. Please note that the API Secret can not be recovered once lost. If you lost this information, please create a new API Secret.

YaYa REST API uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. To authenticate a request, you first concatenate selected elements of the request to form a string. You then use your YaYa API secret to calculate the HMAC of that string. Informally, we call this process "signing the request," and we call the output of the HMAC algorithm the signature, because it simulates the security properties of a real signature. Finally, you add this signature as a parameter of the request by using the syntax described in this section.

These authentication headers are required for all calls to the REST endpoint.

  • YAYA-API-KEY The API key as a string.

  • YAYA-API-TIMESTAMP A timestamp for your request.

  • YAYA-API-SIGN The base64-encoded signature (see Signing a Message section below).

The Authorisation fields in the HTTP header are used to pass user credentials. When authentication fails, the error code 401 (Unauthorised) is returned.

Signing a Message

For the header of YAYA-API-SIGN:

  1. Use API-Secret YAYA-API-SECRET to encrypt the pre-hash string {timestamp+method+endpoint+body} with SHA256 HMAC. The request body is a JSON string and needs to be the same with the parameters passed by the API.

  2. After that, use base64-encode to encrypt the result in step 1 again.

Notice:

  • The encrypted timestamp shall be consistent with the YAYA-API-TIMESTAMP field in the request header.

  • The body to be encrypted shall be consistent with the content of the Request Body.

  • The Method should always be UPPERCASE.

  • The endpoint needs to contain the complete path string but without the base url. e.g. /api/en/user/profile.

  • The body is empty string ("") if there is no request body (typically for GET requests).

This is a cURL example of getting profile information

curl -H "Content-Type:application/json" -H "YAYA-API-KEY:your-api-key" -H "YAYA-API-TIMESTAMP:1673381836197" -H "YAYA-API-SIGN:your-signature" -X POST -d '{"account_name":"12-char-acct"}' {env_base_url}/api/en/user/profile

Selecting a Timestamp

The YAYA-API-TIMESTAMP header MUST be the number of milliseconds since Unix Epoch in UTC. e.g. 1673381836197000

The difference between your timestamp and the API service time must be less than 5 seconds, or your request will be considered expired and rejected.

We recommend using the time endpoint to query for the API server time if you believe there may be a time skew between your server and our API server.

curl -X GET {env_base_url}/api/en/timev