Skip to content
SmartPages Docs

Authentication

An API key can be created for an issuer, and an issuer can have several keys.

This key can only be created through the web interface in Settings → API keys using “Create new key” button. Note that this page is available only when REST API add-on is enabled under Add-ons.

The new key is shown only once, already as [KEY_ID]:[KEY_TOKEN]: the key’s ID, a colon, and the key token. Copy it before pressing “Done!”.

To authenticate, base64 encode that value exactly once and use the result as a Bearer token. Do not add the key ID again: it is already part of what was shown.

  1. Take the key exactly as shown, in the format [KEY_ID]:[KEY_TOKEN] For example: dde8408f-2c3b-499d-926e-5229b0f6680c:400244844d514ea3a63dbaeb0b517a0b
  2. Base64 encode that value
  3. Put the encoded value into the Authorization header like so: Bearer ZGRlODQwOGYtMmMzYi00OTlkLTkyNmUtNTIyOWIwZjY2ODBjOjQwMDI0NDg0NGQ1MTRlYTNhNjNkYmFlYjBiNTE3YTBi

Errors

The API responds with 401 UNAUTHORIZED when a request carries no API key that matches one of your keys, including a missing Bearer prefix. A malformed key can answer 400 instead: an Authorization header value that is not valid header syntax, a Bearer token that is not valid base64, or a key ID that is not a UUID (400 UUID_INVALID).

Call the API from your own server. Browsers cannot call it from your site: cross-origin requests with an API key are refused.

When a request is refused, check for these authentication problems:

  • Deactivated API key
  • Invalid API token or ID
  • Malformed base64 encoding
  • Invalid formatting before base64 encoding
  • Wrong header name (Not using the Authorization header)
  • Missing Bearer prefix

When the API key is valid, the API can still respond with:

  • 403 FORBIDDEN (“Account is not active”) when your SmartPages account is not active
  • 403 ADDON_REQUIRED when an add-on the endpoint needs is not enabled under Add-ons

Error format

Errors from the endpoints come with a JSON body that holds a code, a message and possibleFixes (null when there is no hint), for example:

{
    "error": {
        "code": "ADDON_REQUIRED",
        "message": "Add-on(s) Required: SMS",
        "possibleFixes": [
            "Please go to 'Add-ons' page on SmartPages and make sure SMS add-on(s) are enabled"
        ]
    }
}