Security

DIY Surveys offers Basic and HMAC authentication for API calls. Callbacks can also use HMAC authentication.

[!NOTE] To use any security approach, you need access to an account and must set up access tokens for development.

Basic authentication

Basic authentication is supplied through the request header.

A Basic Access Token can be created in your DIY Surveys account. The AppId is used in the authentication header:

Authorization: Basic AppId

[!NOTE] Basic Authentication is intended to make testing easy with tools such as Postman. HMAC Authentication is recommended for production applications.

HMAC authentication

HMAC authentication calculates a message authentication code using a hash function and a shared secret between the client and server.

An HMAC access token includes:

Attribute	Description
AppId	Application ID used in the encryption/decryption process.
Secret	Secret used by the client.

Encryption process

Step 1

The client builds a string by combining the request data. The string contains six parameters concatenated with no delimiter:

1. AppId.
2. HTTP method.
3. Request URI.
4. Request timestamp.
5. Nonce.
6. Base64 representation of the request payload/body.

The request timestamp uses UNIX time: the number of seconds since 1 January 1970. The nonce is an arbitrary value used only once.

Step 2

Hash the string using SHA-1 and the API key. The result is the request signature.

Step 3

Send the signature in the Authorization header using the X-DIY-Signature scheme.

Authorization: X-DIY-Signature APPId:Signature:Nonce:Timestamp

Step 4

Send the request normally with the generated authorization data.

Decryption process

Step 1

The server receives the request and extracts the AppId, signature, nonce, and request timestamp from the authorization header.

Step 2

The server looks up the AppId in a secure repository to retrieve the API key for that client.

Step 3

The server validates that the request is not a replay request. This uses the timestamp and nonce included in HMAC signature generation. The server checks whether the nonce has been used before within acceptable bounds, such as five minutes.

[!NOTE] If the client is receiving a callback request, the timestamp and nonce checks do not apply.

Step 4

The server rebuilds a string using the same data and ordering used by the client.

Step 5

The server hashes the rebuilt string using SHA-1 and the same API key. If the generated signature matches the supplied signature, the call is authentic. Otherwise, the server returns HTTP 401 Unauthorized.