Skip to main content

Client and authentication

SpatialFlow is the entry point of the SDK. Pass either an API key or a JWT access token, never both.

API key​

Use an API key for server-side code. Keys start with sf_.

import {SpatialFlow} from '@spatialflow/sdk';

const client = new SpatialFlow({apiKey: process.env.SPATIALFLOW_API_KEY});

The client sends the key in the X-API-KEY header. A key needs the scope for each endpoint it calls, such as geofences:read, and some endpoints, such as webhooks, accept only an access token. Create keys under Settings > API Keys, and see Authentication and API keys for the permissions each key needs.

Access token​

Use an access token when requests run on behalf of a signed-in user.

import {SpatialFlow} from '@spatialflow/sdk';

const client = new SpatialFlow({accessToken: 'eyJ...'});

The client sends the token as Authorization: Bearer <token>. It does not refresh the token. Create a new client when the token changes.

The constructor throws an Error if you pass neither option or both.

Options​

OptionTypeDefaultDescription
apiKeystringnoneAPI key
accessTokenstringnoneJWT access token
baseUrlstringhttps://api.spatialflow.ioAPI base URL
timeoutnumber30000Request timeout in milliseconds
maxRetriesnumber3Retries per request for timeouts, connection failures, and 429, 500, 502, 503 and 504 responses. Only GET, HEAD, OPTIONS, PUT and DELETE are retried. 0 turns retries off
import {SpatialFlow} from '@spatialflow/sdk';

const client = new SpatialFlow({
apiKey: process.env.SPATIALFLOW_API_KEY,
baseUrl: 'https://api.spatialflow.io',
timeout: 10_000,
});

Retries wait with exponential backoff, or the Retry-After header when the response has one. A request that still fails after maxRetries retries rejects with its last error. See Errors.

Exported constants​

import {VERSION, DEFAULT_BASE_URL} from '@spatialflow/sdk';

console.log(VERSION, DEFAULT_BASE_URL);

DEFAULT_BASE_URL is the base URL used when you do not set baseUrl. VERSION is the version string the client puts in its User-Agent header.

Resource properties​

The client has one property for each resource. Each is an instance of a generated API class that shares the client's authentication, timeout, and error handling.

PropertyClass
client.geofencesGeofencesApi
client.workflowsWorkflowsApi
client.webhooksWebhooksApi
client.devicesDevicesApi
client.accountAccountApi
client.storageStorageApi

See Resources for the methods.

Per-request options​

Every generated method takes a final options argument. It is an Axios request config, and you can use it to override settings for one call.

import {SpatialFlow} from '@spatialflow/sdk';

const client = new SpatialFlow({apiKey: process.env.SPATIALFLOW_API_KEY});

const response = await client.geofences.appsGeofencesApiGetGeofence(
'3f1b6a52-0000-0000-0000-000000000000',
{timeout: 5000},
);
console.log(response.data.name);