Getting started

The Teleport Cloud API can be used to control Teleport devices and for other interaction with the Teleport Cloud. The API is organized around REST. It uses standard HTTP verbs, authentication and response codes. It accepts JSON-encoded request bodies and also returns JSON-encoded responses. To describe requests and responses, this documentation display them as Typescript interfaces.

The base URL of the Teleport API is https://api.teleport.withthegrid.com.

Authentication

The Teleport API uses tokens to authenticate requests. You must send an Authorization header (Authorization: Bearer [token]) with your request.

Encoding

As stated in the introduction, request and response bodies are JSON-encoded. Date-objects in JSON should be communicated as ISO 8601 strings, specifically as yyyy-mm-ddThh:mm:ss[.mmm]Z.

Demo device

We offer Teleport demo devices. Each demo device is configured for you and set up in the Withthegrid test lab. More details about the Teleport demo devices can be found on the Demo section.

Rate limiting

We apply rate limiting to some endpoints. We follow the IETF RateLimit header fields for HTTP proposal by adding the following headers in the response to rate limited requests:

RateLimit-Limit: the allowed quota of requests in the current time window
RateLimit-Remaining: the remaining quota of requests in the current time window
RateLimit-Reset: the number of seconds until the remaining quota resets to the limit

Some requests are limited by API key, others by asset. Endpoints that are rate limited will mention this and the rate limiting policy. If your remaining quota of requests is 0, your request will be rejected with a 429 status code, see Errors.

Pagination

We apply pagination to the response of some endpoints. We use the Link header to indicate that more results are available. The value of the link header will be Link: <uri-reference>; rel="next";, where uri-reference is an URL encoded relative link, eg. /v1/device?offset=qy39y9.

Endpoints that use pagination will mention this.

Errors

Errors are returned by using the 4xx (for client side) and 5xx (for server side) HTTP status codes. The response contains a JSON-encoded body: { key: string, details?: unknown }. The key is unique for the HTTP status code and can be used for automated client side error handling. The details property (if present) contains debugging information that can help fixing the issue. Specific endpoints can return specific errors, which are listed with that route. In addition, every route can return the following generic errors.

GENERIC ERRORS

400 { "key": "payload_not_readable" }

Payload (body) of the request is not readable, for reasons like an unsupported encoding or invalid size.

400 { "key": "payload_not_json" }

Payload (body) cannot be decoded to JSON.

400 { "key": "payload_invalid" }

Payload (body) does not adhere to the schema. Details are provided in the details property of the response.

400 { "key": "query_invalid" }

The query string does not adhere to the schema. Details are provided in the details property of the response.

400 { "key": "params_invalid" }

The dynamic components in the URL do not adhere to the schema. Details are provided in the details property of the response.

401 { "key": "unauthorized" }

You're not authorized to do this request

401 { "key": "too_many_failed_attempts" }

You've made too many failed login attempts and you are now blocked. Details are provided in the details property of the response.

401 { "key": "invalid_ip" }

You're not authorized to do this request because your IP is not whitelisted

401 { "key": "jwt_expired" }

The JWT that is presented to authenticate the user is expired

403 { "key": "forbidden" }

You're not allowed to do this request

404 { "key": "not_found" }

The server cannot find the requested resource

413 { "key": "payload_too_large" }

Payload (body) too large. The request is limited at 25mb.

429 { "key": "too_many_requests" }

You have exceeded your rate limit.

499 { "key": "client_closed_request" }

Client closed request. You will never see this, as you closed the connection ;)

500 { "key": "internal_server_error" }

An internal server error happened.