Authentication

Every request to the Surfact API requires a token. A token is a unique key that authorizes your requests.

Getting an API token

Your API token is available in the My Profile section of your Surfact account. If you don't yet have API access, request credentials here.

Sending your token

Method 1 — Header (recommended)

Include the token in the request header:

X-Auth-Token: your_token_here

Example:

curl -X GET 'https://api.surfact.com/api/v2.0/devices/' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: your_token_here'

Method 2 — Query parameter

Some endpoints also accept a token query parameter as an alternative to the header. This is convenient for quick prototyping, but the header method is preferred for anything beyond testing, since URLs are more likely to be logged.

curl -X GET 'https://api.surfact.com/api/v1.6/variables/<variable_id>/values/?token=your_token_here'

OAuth2 (web & mobile apps)

For web and mobile applications, Surfact supports OAuth2 bearer tokens. Contact us at [email protected] for implementation details if you are considering this approach.

📘

MQTT authentication

When connecting over MQTT, your token is used as the username (the password can be left blank). See MQTT Authentication.