Get the metadata for the associated reference token. If metadata is associated with the token, it will be returned as originally sent.

/api/v1/single/:referenceToken/metadata

Request

Field

Type

Description

Authorization

String

ALTR API's authorization protocol relies on a properly formatted authorization header. The accepted format is: "ALTR " + api_key + ":" + signature. signature is a base64-encoded, SHA-256 hash that uses the API key's secret as the key for the hash function. The payload being hashed must follow the format:* HTTP-METHOD + "\n" + RESOURCE + "\n" + DATE + "\n". DATE must match X-ALTR-DATE*, and RESOURCE must match the referenceToken in the query string. An example payload for a GET request is: "GET\n" + referenceToken + "\n01-01-1970 00:00:00\n"

X-ALTR-DATE

Date

The datetime used in the authorization signature. If this is more than 15 minutes past the server's internal clock, the request will be rejected.

date = new Date();
payload = 'GET\n' + referenceToken + '\n' + date + '\n';
API_KEY = <your API key>;
SECRET = <your API secret>;
{
    "X-ALTR-DATE": date,
    "Authorization": "ALTR " + API_KEY + ":" + base64(hmac-sha256(payload, SECRET))
}

Parameter

Field

Type

Description

referenceToken

String

The token that is associated with the metadata.

200

Field

Type

Description

success

String

Boolean indicating if the request was successful.

metadata

String

If available, the metadata associated with the token.

{
    "success": true,
    "metadata": "filename.txt"
}

Error Codes

Code

Name

Description

401

unauthorized

The API key could not be authenticated.

403

forbidden

API key does not have read permissions.

404

resource_not_found

The requested resource could not be found.

503

internal_error

The web server encountered an unexpected error.

HTTP/1.1 503 Internal Server Error
{
  "error_type": "internal_error",
  "error_message": "Unable to process request at this time."
}
HTTP/1.1 401 Authentication Required
{
  "error_type": "unauthorized",
  "error_message":  "API key must be included in header."
}
HTTP/1.1 403 Forbidden
{
  "error_type": "forbidden",
  "error_message":  "API key does not have read permissions."
}
HTTP/1.1 404 Not Found
{
  "error_type": "resource_not_found",
  "error_message":  "Token could not be found."
}