Introduction

The Atmosphere v2 HTTP API is based on OpenAPI v3, making it easy to use. It follows RESTful best practices and drastically simplifies the process of registering a new device. Adding a device is accomplished as a POST /v2/devices, and exchanging data with the platform from your embedded device is accomplished via Device Events and Cloud Events (/events/*). The v2 API also provides full capabilities for managing Organizations and Users.

The JSON format of API specification is available at https://platform.atmosphereiot.com/spec. Tools such as Postman can import this URL and automatically generate a comprehensive menu of available operations, with parameters and examples. Just plug in your API key or device token and start submitting requests. We even use the spec in combination with swagger-js to automatically generate code in the Atmosphere IoT web UI.

Getting More Help

Still have questions? Our Forums are the best way to interact with other users and Atmosphere IoT engineers. https://forum.atmosphereiot.com/

Authentication

jwt

This is the preferred authentication scheme, offering the most robust security. A call to /auth/login returns a JSON Web Token (https://jwt.io/), which is then used in subsequent requests.

The JWT issued will expire in 15 minutes, after which time the client should request a new token via /auth/refreshToken (preferred) or via /auth/login.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

refreshToken

Only supported for use with the /auth/refreshToken API method, this is the preferred mechanism for refreshing a JWT that has expired. Clients that support cookies will also receive a cookie containing a refreshToken during a call to /auth/login. This cookie is to be used for fetching a new JWT when the current one expires. This refresh token expires in 14 days, after which the user must login again. Use of this process ensures that sensitive passwords or API keys are transmitted as infrequently as possible.

Security Scheme Type API Key
Cookie parameter name: refreshToken

apiKey

Users may create an API Key for themselves in their user profile settings. These API keys are functionally equivalent to a password, and should be treated as such. Setting this header on each API call is the most convenient mechanism for authenticating with the API. However, this results in transmitting your sensitive key with each request. The recommended approach for API integration is to only use your API key to call /auth/login to fetch a JWT, and then use the JWT for subsequent requests, until it expires. If your client supports cookies, we also recommend using the refreshToken to fetch a new JWT, so that your API Key is only rarely transmitted.

Security Scheme Type API Key
Header parameter name: api_auth_token

apiKeyAlt

Identical to apiKey, except that the key is set in the authorization header.

Security Scheme Type API Key
Header parameter name: authorization

deviceToken

When a device is created, a security token is generated for that device. This token can be used by the device for authorization against specific API calls typically used for device interaction, such as the /events API.

Security Scheme Type API Key
Header parameter name: cloud

auth

Authentication, security tokens, login/logout, etc

Forgot Password

Send an email with a link to reset the user's password.

Request Body schema: application/json
emailOrUsername
required
string

Responses

204

Forgot password request successful

404

Account was not found

post/auth/forgot

Production Server

https://platform.atmosphereiot.com/v2/auth/forgot

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "emailOrUsername": "string"
}

Login

Submit username/password, and receive a JWT in the response for making further requests to the rest of the API.

Request Body schema: application/json
usernameOrEmail
required
string

Can either be a username or e-mail address belonging to an account on the platform.

password
required
string <password>

Responses

201

Login successful

401

Credentials are missing or invalid.

post/auth/login

Production Server

https://platform.atmosphereiot.com/v2/auth/login

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "usernameOrEmail": "string",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "jwtToken": "string",
  • "jwtTokenExpiry": "string"
}

Log out of the platform

Log out of the platform, and invalidate the current user's JWT/refresh tokens. It is the caller's responsibility to provide the tokens which need to be invalidated.

Authorizations:

Responses

204

Logout successful

401

Credentials are missing or invalid.

post/auth/logout

Production Server

https://platform.atmosphereiot.com/v2/auth/logout

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "message": "string",
  • "errors":
    [
    ]
}

Refresh JWT

Authenticates the caller using refreshToken authentication, and returns a JWT, which may be used for subsequent calls to the API.

Authorizations:

Responses

201

successful operation

401

Credentials are missing or invalid.

get/auth/refreshToken

Production Server

https://platform.atmosphereiot.com/v2/auth/refreshToken

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "jwtToken": "string",
  • "jwtTokenExpiry": "string"
}

Register

Creates a new user. Requires that password and passwordConfirmation are set.

Request Body schema: application/json
username
required
string

Username for the user. Must be globally unique. May be same as email.

password
required
string

User's plaintext password. Only used for user creation.

passwordConfirmation
required
string

User's plaintext password. Only used for user creation. Must match password field.

firstName
required
string

User's given name.

lastName
required
string

User's surname.

email
required
string <email>

Email address for the user. Must be globally unique.

company
required
string

Company name for the user.

role
required
string

The user's role.

organizationId
string
tosHash
string
language
string

Responses

201

User created successfully.

400

Bad request.

401

Credentials are missing or invalid.

post/auth/register

Production Server

https://platform.atmosphereiot.com/v2/auth/register

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "username": "string",
  • "password": "string",
  • "passwordConfirmation": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "user@example.com",
  • "company": "string",
  • "role": "developer",
  • "organizationId": "string",
  • "tosHash": "string",
  • "language": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "username": "string",
  • "email": "user@example.com",
  • "role": "technican",
  • "tosHash": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "company": "string",
  • "jobTitle": "string",
  • "language": "string",
  • "createdAt": "2020-11-18T18:08:10Z",
  • "updatedAt": "2020-11-18T18:08:10Z",
  • "lastActive": "2020-11-18T18:08:10Z",
  • "preferences":
    {
    },
  • "imageUrl": "/users/{id}/image.png",
  • "organizationName": "string",
  • "organizationId": "string"
}

Current User

Returns the currently logged-in user.

Authorizations:

Responses

200

successful operation

401

Credentials are missing or invalid.

get/auth/user

Production Server

https://platform.atmosphereiot.com/v2/auth/user

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "username": "string",
  • "email": "user@example.com",
  • "role": "technican",
  • "tosHash": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "company": "string",
  • "jobTitle": "string",
  • "language": "string",
  • "createdAt": "2020-11-18T18:08:10Z",
  • "updatedAt": "2020-11-18T18:08:10Z",
  • "lastActive": "2020-11-18T18:08:10Z",
  • "preferences":
    {
    },
  • "imageUrl": "/users/{id}/image.png",
  • "organizationName": "string",
  • "organizationId": "string"
}

Verify Account

Verify your account with the verification token sent via email.

Request Body schema: application/json
emailOrUsername
required
string

Responses

204

Forgot password request successful

404

Account not found

get/auth/verify

Production Server

https://platform.atmosphereiot.com/v2/auth/verify

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "emailOrUsername": "string"
}

devices

Operations concerning devices

Fetches devices according to the parameters given.

Fetches devices according to the parameters given.

Supported sort fields:

  • name (default)
  • description
Authorizations:
query Parameters
depth
string or integer
Default: 1

Maximum depth of the tree to return results. Default is 1. "all" will return all results.

page
integer <int32> >= 1
Default: 1
Example: page=5

desired page for pagination

limit
integer <int32> [ 1 .. 1000 ]
Default: 100
Example: limit=10

max records to return for pagination

organizationId
string

organization ID query

searchText
string
Example: searchText=SearchString

Filters the results according to entries that match the supplied text. The specific fields searched vary according to the entity.

sortBy
Array of strings
Example: sortBy=?sortBy=firstName&sortBy=-email

Sort the results according to this value. Allowed sort fields varies according to the entity. Optionally, the sort order may be specified by prepending a + for ascending and - for descending. This parameter may be specified multiple times, which will be processed in subsequent order (i.e. first supplied parameter will be primary sort, second supplied parameter will be secondary sort, etc).

Responses

200

successful operation

401

Credentials are missing or invalid.

get/devices

Production Server

https://platform.atmosphereiot.com/v2/devices

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "meta":
    {
    },
  • "data":
    [