Authentication and Authorization

All requests to the Plate API must be authenticated. Authentication is performed using a custom HMAC-based scheme that involves a public key and a signature generated using a secret key. Once a request is authenticated, it is also authorized.

Integration and Key Pair

To authenticate with the Plate API, you must first create an integration in the Plate Dashboard.

• An integration represents a single external application.
• Each integration includes a public key and a secret key (the key pair).
• Each external application should have its own integration and key pair. This ensures you can grant or revoke access individually, without affecting other applications.

Making Authenticated Requests

Every authenticated request must include the following headers:

• Date: The current time, formatted according to RFC 7231.
• Authorization: The HMAC signature of the request.

Requests will be rejected if the date in the Date header is more than 15 minutes off from the server time.

Authorization Header Format

The Authorization header uses the following format:

Authorization: hmac {public_key}:{signature}

• hmac: Literal string indicating the scheme.
• {public_key}: Your integration’s public key.
• {signature}: A base64-encoded HMAC-SHA512 signature of the request.

Calculating the Signature

To generate the signature, construct a string to sign with the following format:

{HTTP_METHOD}
{URL_DOMAIN}
{URL_PATH}
{QUERY_STRING}
{DATE_HEADER}

Use \n to represent line breaks when building the string to sign.

String to Sign Components

Signature Algorithm

• Use the HMAC algorithm from RFC 2104, with the SHA-512 hash function.
• The secret key associated with your public key is used to calculate the HMAC.
• Encode the resulting signature using base64.

Example

Request

• method: GET
• URL:

https://www.startwithplate.com/api/v2/partners/15/sites?paginate_amount=10&paginate_page=2

• Date Header:

Sun, 06 Nov 1994 08:49:37 GMT

String to Sign

GET
www.startwithplate.com
/api/v2/partners/15/sites
paginate_amount=10&paginate_page=2
Sun, 06 Nov 1994 08:49:37 GMT

Calculated Signature (using secret key mysecretkey)

FOjhvBsNceYeVNAJtneSLUeYbNO133Gj1sx+aEu7I8A2ixH3VyYpc6PtxGDGVzpG1EPrDaL7sgurV2Q0+8BHDQ==

Authorization Header

Authorization: hmac mypublickey:FOjhvBsNceYeVNAJtneSLUeYbNO133Gj1sx+aEu7I8A2ixH3VyYpc6PtxGDGVzpG1EPrDaL7sgurV2Q0+8BHDQ==

Error Handling