REST API Endpoints

These endpoints mint the tokens each WebSocket connection needs. Each is used at a different point in the flow — see Authentication tokens for which goes where:

• POST /auth/generateAuthToken (main API) — the SDK token, for initConnection.

• POST /auth/user (streaming) — the producer token, for your app's stream to Terra.

• POST /auth/developer (streaming) — the developer token, for your backend consumer.

Generate a mobile SDK auth token

post

Creates a token to be used with initConnection() functions in the Terra mobile SDKs in order to create a user record for Apple Health or Samsung Health (or equivalent)

Authorizations

x-api-keystringRequired

Your API key for authentication

dev-idstringRequired

Your developer ID for authentication and tracking

Responses

200

200

application/json

statusstringOptionalExample: success

tokenstringOptionalExample: 250c68b9c21b78e40e7a3285a2d538d3bc24aabd3b4c76a782fb0a571ca4501d

expires_inintegerOptionalDefault: 0Example: 180

404

A referenced resource does not exist on Terra's end.

application/problem+json

post/auth/generateAuthToken

POST /api/v2/auth/generateAuthToken HTTP/1.1
Host: access.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: YOUR_API_KEY
Accept: */*

{
  "status": "success",
  "token": "250c68b9c21b78e40e7a3285a2d538d3bc24aabd3b4c76a782fb0a571ca4501d",
  "expires_in": 180
}

Stream - Generate developer token

post

Generates a single-use token for a developer (consumer) connection.

Authorizations

x-api-keystringRequired

Your API key for authentication

dev-idstringRequired

Your developer ID for authentication and tracking

Responses

200

Token generated.

application/json

tokenstringRequired

Single-use token to present in the IDENTIFY frame.

Example: cG9RvLY5.yvKm778XMIPm1ig93BJEoRCVGHzlrBNjzWdeXePTaMM

400

Missing or malformed authentication headers.

403

Invalid developer credentials.

500

Token generation failed.

post/auth/developer

POST /auth/developer HTTP/1.1
Host: ws.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: YOUR_API_KEY
Accept: */*

{
  "token": "cG9RvLY5.yvKm778XMIPm1ig93BJEoRCVGHzlrBNjzWdeXePTaMM"
}

Stream - Generate user token

post

Generates a single-use token for a user (producer) connection. The id identifies the user the token is scoped to — a v6 connection id or a v5 compatibility user UUID — and must belong to the authenticating developer.

Authorizations

x-api-keystringRequired

Your API key for authentication

dev-idstringRequired

Your developer ID for authentication and tracking

Query parameters

idstringRequired

The id of the user to generate a token for.

Responses

200

Token generated.

application/json

tokenstringRequired

Single-use token to present in the IDENTIFY frame.

Example: OTYwNWFi5ZWQMTAxMjg0Y2Qw.gzrPzZcS3Gy8QDOxbiPRwu30PTB3VxW0eE

400

Missing id parameter, or missing/malformed authentication headers.

403

Invalid credentials, or the user does not belong to this developer.

500

Token generation failed.

post/auth/user

POST /auth/user?id=text HTTP/1.1
Host: ws.tryterra.co
x-api-key: YOUR_API_KEY
dev-id: YOUR_API_KEY
Accept: */*

{
  "token": "OTYwNWFi5ZWQMTAxMjg0Y2Qw.gzrPzZcS3Gy8QDOxbiPRwu30PTB3VxW0eE"
}