The SafeTrek Developer Hub

Welcome to the SafeTrek developer hub. You'll find comprehensive guides and documentation to help you start working with SafeTrek as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Overview

 

The SafeTrek API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

Authentication

 

OAuth2

The SafeTrek API uses OAuth2 over SSL for authentication and authorization. You may find this straightforward if you've worked with OAuth2 before.

Access tokens

To use the SafeTrek API, your app must send an OAuth2 access token in an Authorization header with each request. Currently, there is only one way of retrieving access tokens.

If you are requesting access to a SafeTrek user's account in order to make requests on their behalf, you will go through a "3-legged" flow.

3-Legged flow for accessing user-specific endpoints

To create alarms, the user must grant you access. Users who don't have a SafeTrek account will be prompted to create a new account if they are directed through the following flow.

Step 1: Obtaining access to the user's SafeTrek account

First, direct the user to the following URL (hosted by SafeTrek) with query parameters set appropriately for your application. The user will see information about your application, along with the list of permissions your application is requesting. The user can indicate whether SafeTrek should grant access to your application or not.

Parameter
Description

client_id

your application's client ID

response_type

at this time, the only supported value is code

scope

the space-delimited list of scopes which your application is requesting

state

a payload which will be passed back to your application through the redirect

redirect_uri

your redirect URI

Sandbox Environment

For testing, use https://account-sandbox.safetrek.io/authorize for the authorization URL.

# This request should originate from the logged-in user
GET https://account.safetrek.io/authorize?
	client_id=<client_id>&
	scope=openid phone offline_access&
	state=<state_string>&
	response_type=code&
	redirect_uri=<redirect_uri>

Step 2: Handling the redirect

If the SafeTrek user grants your application access to the requested permissions, SafeTrek will issue a 302 redirect to the Redirect URI you've set up with SafeTrek, along with an authorization code as a URL parameter. The authorization code should be used in the next step. It is a one-time use code and it will appear on your server like this:

GET 'https://your-redirect-uri/?code=<authorization_code>'

If you need help debugging the response to your server, consider configuring the Redirect URI as http://localhost or using a RequestBin.

Step 3: Retrieving an access token

Your server should retrieve a one-time-use authorization_code and pass it to SafeTrek in order to retrieve an access token. The access token will enable you to make requests on behalf of the SafeTrek user. Remember to include your application's client_id and client_secret in the POST body, as demonstrated below.

Sandbox Environment

For testing, use https://login-sandbox.safetrek.io/oauth/token for the token URL.

# This request comes from your server
curl -X POST -H "Content-Type: application/json" \
     -d '{"grant_type": "authorization_code", "code": <authorization_code>, "client_id": <client_id>, "client_secret": <client_secret>, "redirect_uri": <redirect_uri>}' \
     'https://login.safetrek.io/oauth/token'
POST /oauth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": <authorization_code>,
  "client_id": <client_id>,
  "client_secret": <client_secret>,
  "redirect_uri": <redirect_uri>
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": <access_token>,
  "refresh_token": <refresh_token>,
  "token_type": "bearer",
  "expires_in": 36000,
  "scope": "space delimited string of scopes"
}

Step 4: Use the access token

API requests which require access tokens can now use the access_token returned from Step 3. When making requests you'll provide this access_token in the Authorization header, like in the example below:

curl -X POST \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "services": {
      "police": false,
      "fire": false,
      "medical": true
    },
    "location.coordinates": {
      "lat": 34.32334,
      "lng": -117.3343,
      "accuracy": 5
    }
}' \
https://api.safetrek.io/v1/alarms

The access token expires after 10 hours, so you will need to refresh the tokens thereafter.

Step 5: Refreshing the access token

When the user's access token has expired, you may obtain a new access token by passing the refresh_token returned above. As with all POSTs in the 3-legged flow, remember to include your application's client_id and client_secret in the POST body.

Sandbox Environment

For testing, use https://login-sandbox.safetrek.io/oauth/token for the token URL.

curl -X POST -H "Content-Type: application/json" \
     -d '{"grant_type": "refresh_token", "client_id": <client_id>, "client_secret": <client_secret>, "refresh_token": <refresh_token>}' \
     'https://login.safetrek.io/oauth/token'
POST /oauth/token HTTP/1.1
Host: login.safetrek.io
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": <client_id>,
  "client_secret": <client_secret>,
  "refresh_token": <refresh_token>
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": <access_token>,
  "token_type": "bearer",
  "expires_in": 36000,
  "scope": "space delimited string of scopes"
}

Step 6: Revoking the refresh token

If your application no longer needs access to the user's account, you can revoke the refresh token by passing it to the /oauth/revoke endpoint, including your application's client_id and client_secret in the POST body. As demonstrated below, we expect the refresh token you're revoking as JSON data in the body of the request.

Sandbox Environment

For testing, use https://login-sandbox.safetrek.io/oauth/revoke for the revoke URL.

curl -X POST -H "Content-Type: application/json" \
     -d '{"client_id": <client_id>, "client_secret": <client_secret>, "refresh_token": <refresh_token>}' \
     'https://login.safetrek.io/oauth/revoke'
POST /oauth/revoke HTTP/1.1
Host: login.safetrek.io
Content-Type: application/json

{
  "client_id": <client_id>,
  "client_secret": <client_secret>,
  "refresh_token": <refresh_token>
}
HTTP/1.1 200 OK

Errors

 

The SafeTrek API uses conventional HTTP status codes to indicate success or failure. Responses with a status code starting with 4xx or 5xx can be considered as failed. The API returns errors in JSON format in following structure:

{
  "code": 400,
  "message": "Bad Request",
  "details": "A required field is missing"
}

Developer-friendly API

SafeTrek attempts to provide a developer-friendly API, hence sometimes you can find a hint how to fix an error right in its details (like in the example above).

Attributes
Description

code

The HTTP status code of error returned. Can be: 2xx, 4xx or 5xx

key

For API object errors, a short string from amongst those listed below describing the kind of error that occurred

message

A human-readable message providing short description about the error

details

A human-readable message providing more details about the error

Key
Description

resource_not_found

Entity with provided id does not exist

invalid_payload

A request body is invalid and cannot be processed

alarm_canceled

The alarm has already been canceled and can no longer be modified

Alarm Object

 

Sandbox Environment

For testing, use https://api-sandbox.safetrek.io/v1 as the base URL.

Attributes
Description
Example

id
string

ID for the alarm

507f191e810c19729de860ea

status
string

Current status of the alarm
Can be either ACTIVE or CANCELED

ACTIVE

services
object

Services for the alarm

{
  "police": true,
  "fire": false,
  "medical": false
}

locations
object

Current and previous locations of the alarm given using either address or coordinates.

{
  "adresses": [{
    "line1": "1234 9th Ave", 
    "line2": "Unit 302", 
    "city": "San Diego", 
    "state": "CA", 
    "zip": "92101",
    "created_at": "2017-09-23T18:01:50Z"
  }],
  "coordinates": [{
    "lat": 34.32334,
    "lng": -117.3343,
    "accuracy": 5,
    "created_at": "2017-09-23T17:59:02Z"
  }]
}

created_at
string

Time the alarm was created

2017-09-23T17:59:02Z

Alarm Metadata

If you have additional contextual information to send with alarms, contact us to enable it for your account.

Create Alarm

Method to create an alarm

 
posthttps://api.safetrek.io/v1/alarms
curl -X POST \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "services": {
      "police": false,
      "fire": false,
      "medical": true
    },
    "location.coordinates": {
      "lat": 34.32334,
      "lng": -117.3343,
      "accuracy": 5
    }
}' \
https://api.safetrek.io/v1/alarms
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "id": "507f191e810c19729de860ea",
  "status": "ACTIVE",
  "services": {
    "police": false,
    "fire": false,
    "medical": true
  },
  "locations": {
    "addresses": [],
    "coordinates": [{
      "lat": 34.32334,
      "lng": -117.3343,
      "accuracy": 5,
      "created_at": "2017-09-23T17:59:02Z"
    }]
  },
  "created_at": "2017-09-23T17:59:02Z"
}

Body Params

services
object

Services required for the alarm
Defaults to just police

services.police
boolean

Whether or not police services are required

services.fire
boolean

Whether or not fire services are required

services.medical
boolean

Whether or not medical services are required

location
object
location.coordinates
object

The initial location of the alarm
Either this or location.address must be provided

location.coordinates.lat
double

Latitude

location.coordinates.lng
double

Longitude

location.coordinates.accuracy
integer

Accuracy in meters

location.address
object

The initial location of the alarm
Either this or location.coordinates must be provided

location.address.line1
string

Number and street

location.address.line2
string

Apt, suite, unit, etc.

location.address.city
string

City

location.address.state
string

State abbreviation (i.e. MO for Missouri)

location.address.zip
string

5 digit zip code

 

Update Alarm Location

Method to update an alarm's current location

 
posthttps://api.safetrek.io/v1/alarms/id/locations
curl -X POST \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "coordinates": {
      "lat": 40.3625,
      "lng": -130.5214,
      "accuracy": 5
    }
}' \
https://api.safetrek.io/v1/alarms/507f191e810c19729de860ea/locations
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "coordinates": {
    "lat": 40.3625,
    "lng": -130.5214,
    "accuracy": 5,
    "created_at": "2017-09-23T18:01:50Z"
  }
}

Path Params

id
string
required

ID of the alarm to be updated

Body Params

coordinates
object

Current location of the alarm
Either this or address must be provided

coordinates.lat
double

Latitude

coordinates.lng
double

Longitude

coordinates.accuracy
integer

Accuracy in meters

address
object

Current location of the alarm
Either this or coordinates must be provided

address.line1
string

Number and street

address.line2
string

Apt, suite, unit, etc.

address.city
string

City

address.state
string

State abbreviation (i.e. MO for Missouri)

address.zip
string

5 digit zip code

 

Update Alarm Status

Method to update an alarm's status

 
puthttps://api.safetrek.io/v1/alarms/id/status
curl -X PUT \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CANCELED",
    "pin": "1234"
}' \
https://api.safetrek.io/v1/alarms/507f191e810c19729de860ea/status
A binary file was returned

Your OAuth2 token is incorrect or has expired

    
{
  "code": 400,
  "message": "Bad Request",
  "key": "invalid_payload",
  "details": "Provided PIN is invalid or incorrect"
}
{
  "code": 400,
  "message": "Bad Request",
  "key": "alarm_canceled",
  "details": "The alarm has already been canceled and can no longer be modified"
}

Path Params

id
string
required

ID of the alarm to be updated

Body Params

status
string
required

The status of the alarm
Currently can only be CANCELED

pin
string

An optional parameter to verify the user's PIN before canceling

 

Get Alarm Status

Method to get an alarm's status

 
gethttps://api.safetrek.io/v1/alarms/id/status
curl -X GET \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
https://api.safetrek.io/v1/alarms/507f191e810c19729de860ea/status
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "status": "CANCELED" //or ACTIVE
}

Path Params

id
string
required

ID of the alarm to get the status for

 

Verification Object

 

Sandbox Environment

For testing, use https://api-sandbox.safetrek.io/v1 as the base URL.

Attributes
Description
Example

pin
string

The user's PIN

1234

Create Verification

Method to create a verification request

 
posthttps://api.safetrek.io/v1/verifications
curl -X POST \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pin": "1234"
}' \
https://api.safetrek.io/v1/verifications
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
  "pin": true //or false
}
{
  "code": 400,
  "message": "Bad Request",
  "key": "invalid_payload",
  "details": "Invalid verification request body"
}

Body Params

pin
string

The user's PIN you are trying to verify