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

Option	Type	Default	Description
apiKey	string	none	API key
accessToken	string	none	JWT access token
baseUrl	string	https://api.spatialflow.io	API base URL
timeout	number	30000	Request timeout in milliseconds
maxRetries	number	3	Accepted and stored, but the client does not retry requests today

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

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

Because maxRetries has no effect, handle RateLimitError and ServerError in your own code. 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.

Property	Class
client.geofences	GeofencesApi
client.workflows	WorkflowsApi
client.webhooks	WebhooksApi
client.devices	DevicesApi
client.account	AccountApi
client.storage	StorageApi

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);