NAV Navbar
Logo

Introduction

Welcome to the connctd.io API. This REST based API provides functionality to create, manage and update Things and other resources in the world of IoT.

Authentication

To authenticate against our API you need verify your credentials. In return you receive a token identifying you as the resource owner (user), granting you a certain amount of permissions.

Login

The response will either have the status code 200 in case of success or 401 in case the supplied credentials can’t be verified. In error cases a default error object is returned in the body.

Request: Method: POST Url: https://api.connctd.io/api/v1/auth/login Content-Type: application/json Body: see below

{
  "email":"yourmail",
  "password":"yourpassword"
}

Response: Code: 200 Body: Token und further information. See example below

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NpZCI6I.....",
  "user_id": "546",
  "user_uuid": "4bbb4e40-99ea-43c6-9447-a4c67f563e1c"
}

Logout

Invalidates the access token. You have to specify your access token within Authorization header field.

Request: Method: POST Url: https://api.connctd.io/api/v1/auth/logout Content-Type: application/json Body: empty

Response: Code: 200 Body: Empty

OAuth 2.0

The connctd platform acts as a oauth2 provider implementing all flows described in https://tools.ietf.org/html/rfc6749#section-4 except the “Resource Owner Password Credentials Grant”. The following two sections mainly focus on the Authorization Code Grant Flow as there already exist hundreds of good oauth2 tutorials which can be read in case you need another flow.

Requesting Authorization

This request will redirect the user to the consent screen. You have to replace the example parameter values with the corresponding values of your app. A detailed parameter description can be found here.

Request: Method: GET Url: https://api.connctd.io/oauth2/auth?state=abcdefghiklmnop&client_id=1bd2f1a3-e72d-4606-b82b-86d1054f3bd4&redirect_uri=https%3A%2F%2Fabc%2Fauth%2Fcallback&response_type=code&scope=connctd.units.read+connctd.things.read+connctd.connector+offline

Response: Code: 301

Requesting a token

This request requires the authentication of the app by specifying an Authorization header with value Basic base64_encode(client_id:client_secret) The body will contain a url encoded form with the fields grant_type, code, redirect_uri and client_id

Request: Method: POST Url: https://api.connctd.io/oauth2/token Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=-auth code from reply of prev request-&
redirect_uri=http%3A%2F%2Fabc.com%%2Fauth%2Fcallback&client_id=1bd2f1a3-e72d-4606-b82b-86d1054f3bd4

Response: Code: 200

{
    "access_token":"...",
    "refresh_token":"...",
    "scope":"...",
}

Requesting an app token

This is the so called client credentials grant flow and allows an app to fetch an acccess token that is NOT user related. This is required for e.g. registering an app callback (see apps)

Request: Method: POST Url: https://api.connctd.io/oauth2/token Content-Type: application/x-www-form-urlencoded Authorization: Basic ——

grant_type=client_credentials&scope=connctd.connector

Authorization header value needs to be of format: base64_encode(client_id:client_secret)

Response: Code: 200

{
    "access_token":"..."
}

Apps

connctd implements the OAuth 2.0 specification. By doing so developers can write and host their own apps that can obtain limited access to resources on behalf of the user. Such an app (in OAuth terms it is called client) could for example list the units and things of an user or it could be used to administrate access permissions for resources. These apps do not just consume resources they might also deliver new resources like for example things. A common use case for connctd apps are apps that mediate between our platform and another, foreign technology. We often name those apps “connector” as they are translating from a remote domain model into our thing concept. If you are unfamiliar with the OAuth 2.0 framework we highly recommend reading the specification. In case you are uncertain regarding some parameters we also recommend reading the documentation of hydra - the framework we are using under the hood for OAuth 2.0 support.

Register an app

Registers a new application

redirect_uris: Array of redirect uris that are later on used in various flows

scope: Space separated list of scopes. The offline scope is necessary if a refresh token should be later on generated. You can see in a list of all available scopes within the scopes section

public: You have to set this to true if there exists the possibility of client secret disclosure (e.g. Android app might be decompiled). Apps with setting public=true will not be able to register action callback urls since the client_credentials grant type flow is required for that but which is deactivated due to security concerns with public apps.

visible: If set to true any user can see your app (e.g. in an app store). If set to false only you can see the app.

tags: Used to search for apps with specific meanings (e.g. Smart Home, Netatmo, Assisted living)

As a response you will get back a client_id, id and a client_secret. The client_secret needs to be stored as it can’t be retrieved again. Right now the id of the created client (used for managing clients) is equal to the oauth2 client_id (required for OAuth2 flow).

Request: Method: POST Url: https://api.connctd.io/api/v1/apps Content-Type: application/json Body: see below

{
  "name":"Name of application",
  "description":"Any description",
  "homepage":"https://abc.com",
  "redirecturis":["https://abc.com/auth/callback"],
  "policyuri":"https://abc.com/policy",
  "tosuri":"https://abc.com/tos",
  "logouri":"https://abc.com/logo.png",
  "scopes": ["connctd.units.read","connctd.connector","connctd.things.read","offline","openid"],
  "public":true,
  "visible":true,
  "tags":[{"name":"Smart Home"}],
  "contacts":["your.mail@mail.com"],
  "responsetypes": [
    "code",
    "token",
    "id_token"
  ],
  "granttypes": [
    "authorization_code",
    "implicit",
    "refresh_token",
    "password",
    "client_credentials"
  ]
}

Response: Code: 201 Body: Newly created application. See example below.

{
  "id": "f62794f6-659d-439a-b19b-45e6cf705cef",
  "client_id": "f62794f6-659d-439a-b19b-45e6cf705cef",
  "client_secret": "NWx.W-B>G/!u"
}

Required scope: connctd.core

Retrieve apps

Retrieves a list of all apps

Request: Method: GET Url: https://api.connctd.io/api/v1/apps

Response: Code: 200 Body: List of apps. See example below

[
  {
      "id": "f62794f6-659d-439a-b19b-45e6cf705cef",
      "name":"Name of application",
      "description":"Any description",
      "public": true,
      "added": 1497866109,
      "owner": "7",
      "tags": [
          {
              "name": "Smart Home"
          }
      ],
      ...
  },
  ...
]

Required scope: connctd.core

Retrieve an app

Retrieves a specific app

Request: Method: GET Url: https://api.connctd.io/api/v1/apps/f62794f6-659d-439a-b19b-45e6cf705cef

Response: Code: 200 Body: Single app description. See example below

{
  "id": "f62794f6-659d-439a-b19b-45e6cf705cef",
  "name":"Name of application",
  "description":"Any description",
  ...
}

Required scope: connctd.core

Add tag

Adds a new tag to the tag list of an app

Request: Method: POST Url: https://api.connctd.io/api/v1/apps/f62794f6-659d-439a-b19b-45e6cf705cef/tags Body: see below

{
  "name":"My new tag"
}

Response: Code: 201

Required scope: connctd.core

Delete a tag

Removes a tag

Request: Method: DELETE Url: https://api.connctd.io/api/v1/apps/1bd2f1a3-e72d-4606-b82b-86d1054f3bd4/tags/TAGNAME

Response: Code: 204

Delete an app

Removes an app by client_id

Request: Method: DELETE Url: https://api.connctd.io/api/v1/apps/1bd2f1a3-e72d-4606-b82b-86d1054f3bd4

Response: Code: 204

Required scope: connctd.core

Register a callback url

Request: Method: POST Url: https://api.connctd.io/api/v1/actions/callback/register Authorization: Bearer app-token

This request stores a system wide callback url for all action requests that are related to this app. This is important whenever an app creates things that contain actions. As soon a user triggers any of these actions by performing an action request the request is forwarded to the given callback url. The header requires a valid app token. See section oauth2 -> Register an app token for more information about gaining app tokens

{
  "CallbackUrl":"https://remote-service-url"
}

Response: Code: 200

Units

A unit is a primitive container that gives developers the possibility to group things and to put them into a context. Since a unit can reference other units (children and parents) even complex structures of the real world can be modeled like for example a city with it’s streets and buildings.

Model

{
  "id": "<Generated id>",
  "name": "<Name of unit>",
  "type": "<Type of unit>",
  "things": [{"href":"https://api.connctd.io/api/v1/things/ab..."}],
  "properties": ["tuple(name,value)"],
  "children": [{"href":"https://api.connctd.io/api/v1/units/xy..."}],
  "parents": [{"href":"https://api.connctd.io/api/v1/units/qw..."}],
  "subjects": [{"href":"https://api.connctd.io/api/v1/subjects/98..."}],
  "owner": "65...."
}

On the right hand side you can see an exemplary unit. We also offer a unit json schema which allows json object validation.

The unit type helps to interprete the meaning of a unit.

The values of the properties parents, children, subjects and things are lists holding references to other resources.

Create unit

{
  "name": "My House",
  "type": "HOUSE",
  "properties": [
    {
      "name":"number",
      "value":"25"
    }
  ]
}

Response: Code: 201 Body: Id of newly created unit. See example below

{
  "id": "e1de3bcf-7699-4838-97ec-635618fb3caa"
}

Creates an empty unit. Additional information like parents, children or subjects can be added by subsequent calls.

Required scope: connctd.units.admin or connctd.core

Request: Method: POST Url: https://api.connctd.io/api/v1/units Content-Type: application/json Body: see below

Retrieve units

Request: Method: GET Url: https://api.connctd.io/api/v1/units

Response: Code: 200 Body: Array of units. See example below

[
  {
    "href": "https://api.connctd.io/api/v1/units/37cbbcfb-9a5c-4931-aa55-f73ff0af0e80"
  }, ...
]

Retrieves a list of resource links to units the user belongs to

Required scope: connctd.units.read or connctd.core

Retrieve unit

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-

Response: Code: 200 Body: A single unit. See example below

{
  "id": "e1de3bcf-7699-4838-97ec-635618fb3caa",
  "name": "My House",
  "type": "HOUSE",
  "things": [],
  "properties": [
    {
      "name": "number",
      "value": "25"
    }
  ],
  "children": [],
  "parents": [],
  "subjects": [],
  "owner": "1"
}   

Retrieves a unit by id

Required scope: connctd.units.read or connctd.core

Update unit

Request: Method: PATCH Url: https://api.connctd.io/api/v1/units/-unitId-

{
  "name":"newname",
  "type":"newtype"
}

Response: Code: 204 Body: empty. See example below

Updates type and name properties

Required scope: connctd.units.read or connctd.core

Delete unit

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-

Response: Code: 204

Removes a unit by its id.

Required scope: connctd.units.admin or connctd.core

Get unit references

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/-parents|children-

Response: Code: 200 Body: List of unit references. See example below

[
  {
    "href": "https://api.connctd.io/api/v1/units/1376f734-dbfc-486d-b264-f62d3ff88579"
  }, ...
]

Retrieves a list of unit references.

Required scope: connctd.units.read or connctd.core

Add unit reference

Request: Method: POST Url: https://api.connctd.io/api/v1/units/-unitId-/-parents|children- Content-Type: application/json Body: Id of parent/child unit. See example below

{
  "id": "1376f734-dbfc-486d-b264-f62d3ff88579"
}

Response: Code: 201

Adds a reference to another unit. The reference also appears within the referenced unit either as parent or child reference.

Required scope: connctd.units.admin or connctd.core

Remove unit reference

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-/-parents|children- Content-Type: application/json Body: Id of parent/child unit. See example below

{
  "id": "1376f734-dbfc-486d-b264-f62d3ff88579"
}

Response: Code: 204

Removes a reference to another unit. The reference also disappears from within the referenced unit.

Required scope: connctd.units.admin or connctd.core

Get subject references

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/subjects

Response: Code: 200 Body: List of subject references. See example below

[
  {
    "href": "https://api.connctd.io/api/v1/subjects/123-55664-aab-2456"
  }
]

Retrieves list of subject references

Required scope: connctd.units.read or connctd.core

Add subject reference

Request: Method: POST Url: https://api.connctd.io/api/v1/units/-unitId-/subjects Content-Type: application/json Body: Id of subject. See example below

{
  "id": "123-55664-aab-2456"
}

Response: Code: 201

Adds a reference to a subject.

Required scope: connctd.units.admin or connctd.core

Remove subject reference

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-/subjects Content-Type: application/json Body: Id of subject. See example below

{
  "id": "123-55664-aab-2456"
}

Response: Code: 204

Removes a reference to a subject.

Required scope: connctd.units.admin or connctd.core

Get properties

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/properties

Response: Code: 200 Body: List of properties. See example below

[
  {
    "name": "number",
    "value": "25"
  }
]

Retrieves a list of all properties

Required scope: connctd.units.read or connctd.core

Get property

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/properties/-propertyName-

Response: Code: 200 Body: A single property. See example below

{
    "name": "number",
    "value": "25"
}

Read a specific property

Required scope: connctd.units.read or connctd.core

Add property

Request: Method: POST Url: https://api.connctd.io/api/v1/units/-unitId-/properties Content-Type: application/json Body: New property. See example below

{
    "name": "MyNewProperty",
    "value": "123"
}

Response: Code: 201

Adds a new property.

Required scope: connctd.units.admin or connctd.core

Update property

Request: Method: PUT Url: https://api.connctd.io/api/v1/units/-unitId-/properties/-propertyName- Content-Type: application/json Body: New property value. See example below

{
    "name": "MyNewProperty",
    "value": "123"
}

Response: Code: 204

Updates a property.

Required scope: connctd.units.admin or connctd.core

Delete property

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-/properties/-propertyName-

Response: Code: 200

Removes a property from property set

Required scope: connctd.units.admin or connctd.core

Get thing references

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/things

Response: Code: 200 Body: List of thing references. See example below

[
  {
    "href": "https://api.connctd.io/api/v1/things/591327fe-5c1a-4dbb-a96b-9bef4de0a273"
  }, ...
]

Retrieves a list of all thing references

Required scope: connctd.units.read or connctd.core

Add thing reference

Request: Method: POST Url: https://api.connctd.io/api/v1/units/-unitId-/things Content-Type: application/json Body: Id of thing. See example below

{
    "id": "591327fe-5c1a-4dbb-a96b-9bef4de0a273"
}

Response: Code: 201

Adds a reference to a things.

Required scope: connctd.units.admin or connctd.core

Remove thing reference

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-/things Content-Type: application/json Body: Id of thing. See example below

{
    "id": "591327fe-5c1a-4dbb-a96b-9bef4de0a273"
}

Response: Code: 204

Removes a reference to a thing.

Required scope: connctd.units.admin or connctd.core

Things

Things in our API are abstract representations of specific IoT related devices. They can be created, deleted and managed with our API. Depending on the requested action the supplied token must have certain scopes.

Available scopes for Things:

Create Thing

To add a Thing you need to acquire a token with the scope connctd.connector through the OAuth2 process. After this you are able to create Things with the following request

Request: Method: POST Url: https://api.connctd.io/api/v1/things Content-Type: application/json Body: see below

{
  "id": "<unique-thing-id>",
  "name": "<human readable name>",
  "manufacturer": "<human readbale manufacturer name>",
  "displaytype": "<hint for display purposes>",
  "maincomponentid": "<id of the main component>",
  "components": [
    {
      "id": "<thing unique id of component>",
      "name": "<human readable name of component>",
      "componenttype": "<type of the component>",
      "capabilities": ["<one ore more capabaliies>"],
      "properties": [
        {
          "name": "<component unique name of property>",
          "value": "<string representation of the value>",
          "unit": "<short name of unit of measurement>",
          "type": "<data type of value (NUMBER,STRING,BOOLEAN)>"
        }
      ],
      "actions": [
        {
          "name": "<component unique name of action>",
          "parameters": [
            {
              "name": "<parameter name>",
              "type": "<type of parameter(NUMBER,STRING or BOOLEAN>"
            }
          ]
        }   
      ]
    }
  ]
}

Response: Code: 201 Body: Id of newly created thing. See example below

{
  "Id": "f6088362-a864-4834-89eb-d9e4dafbaefe"
}

Required scope: connctd.connector

Retrieve things

Retrieves a list of all things the subject is owner of. Be aware that this list does NOT contain things that are shared via policies with the subject.

Required scope: connctd.things.read or connctd.core

Request: Method: GET Url: https://api.connctd.io/api/v1/things

Response: Code: 200 Body: List of thing references. See example below

[
  {
    "href": "https://api.connctd.io/api/v1/things/1376f734-dbfc-486d-b264-f62d3ff88579"
  }, ...
]

Retrieve thing

Retrieves a single thing.

Required scope: connctd.things.read or connctd.core

Request: Method: GET Url: https://api.connctd.io/api/v1/things/-thingid-

Response: Code: 200 Body: Thing. See example below

{
    "id": "177e3f1a-ef98-4898-b277-b6b392720be9",
    "name": "TutorialDummyThing",
    "manufacturer": "Tutorial app",
    "displayType": "LAMP",
    "mainComponentId": "lamp",
    "componentLinks": [
        {
            "href": "https://api.connctd.io/api/v1/things/177e3f1a-ef98-4898-b277-b6b392720be9/components/lamp"
        }
    ],
    "attributes": null
}

Retrieve thing component

Retrieves the component of a thing.

Required scope: connctd.things.read or connctd.core

Request: Method: GET Url: https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-

Response: Code: 200 Body: Thing component. See example below

{
    "id": "lamp",
    "name": "Lamp",
    "componentType": "LAMP",
    "capabilities": [
        "SWITCHABLE"
    ],
    "propertyLinks": [
        {
            "href": "https://api.connctd.io/api/v1/things/177e3f1a-ef98-4898-b277-b6b392720be9/components/lamp/properties/on"
        }
    ],
    "actions": [
        {
            "name": "setOn",
            "parameters": [
                {
                    "name": "on",
                    "type": "BOOLEAN"
                }
            ]
        }
    ]
}

Retrieve component property

Retrieves the property of a component.

Required scope: connctd.things.read or connctd.core

Request: Method: GET Url: https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/properties/-propertyName-

Response: Code: 200 Body: Component property. See example below

{
    "name": "on",
    "value": "false",
    "unit": "ONOFF",
    "type": "BOOLEAN",
    "lastUpdate": "2017-08-23T14:10:53Z"
}

Trigger action request

Used to trigger actions offered by a component. The content of the body depends on the action parameters which can be found in the action description of the corresponding thing component. Action requests will be sent to the callback urls corresponding to the connector/app that has created the app (see Apps->Register a callback url).

Required scope: connctd.things.action

Request: Method: POST Url: https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/actions/-actionName-

{
  "on":"true"
}

Response: Code: 201 Body: Thing component. See example below

{
    "id": "ebfc9fa6-5eb6-4217-bde5-3439797c4577",
    "status": "COMPLETED",
    "deadline": "2017-08-30T15:00:08.941380198Z"
}

Update thing property

This endpoint lets you update a property of a Thing you created. The supplied value must be a valid representation of the property type of this property.

Required scope: connctd.connector

Request: Method: PUT Url: https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/properties/-propertyname-

{
    "value": "xyz"
}

Response: Code: 200 Body: Empty body

Delete thing

If the supplied bearer token has the scope connctd.connector and the Thing with the specified id was created by the application belongig to the bearer token, this request will delete the specified Thing.

Required scope: connctd.connector

Request: Method: DELETE Url: https://api.connctd.io/api/v1/things/-thingid-

Response: Code: 200 Body: Empty body

Policies

Whenever a unit or thing is created it belongs to a specific subject and thus can only be seen by that subject. Policies allow a subject to share resources with other subjects. Depending on the policy settings a policy can give e.g. access to a complete thing or only parts and specific actions of a thing like a single sensor reading.

Model

{
  "id": "<generated id>",
  "description": "<description of policy>",
  "subjects": ["<subject id>"],
  "resources": ["<resource id>"],
  "actions": ["GET", "UPDATE", "CREATE", "DELETE"],
  "effect": "<allow|deny>"
  "owner": "<who created the policy>"
}

On the right hand side you can see the model of a policy on how it is stored within our database.

The subjects parameter holds a list of subject ids (represented as plain strings) indicating to which subjects the policy will take effect to. resources is a list of resource names and defines to which resources the policy will apply. See the section Create policy for a detailed description on to specify resources. The parameter actions controls the actions that will be allowed by the subjects on the defined resources. As soon as a policy fits the effect finally determines whether the access will be allowed or denied. The effect value allow will be used in most cases. Usage of deny makes sense if you have defined overlapping policies. In those cases a deny policy will always win over an allow policy.

Create policy

Creates a policy that is applied to given subjects as soon as request fits one of given resources.

Request: Method: POST Url: https://api.connctd.io/api/v1/policies Content-Type: application/json Body: see below

{
  "description":"Dummy policy",
  "resources":["resource:things:f85eb546-e791-4642-86b1-a981678dcf31", "resource:things:f85eb546-e791-4642-86b1-a981678dcf31:*"],
  "subjects":["122f0260-2506-44b6-8d08-574ad27d7529", "a21f9779-c44e-4e70-9f3c-16e31a93094b"],
  "effect":"allow",
  "actions":["GET"]
}

Response: Code: 201 Body: Id of newly created policy. See example below

{
  "id": "f6088362-a864-4834-89eb-d9e4dafbaefe"
}

A Resources describes an entity within the connctd platform. Right now we support referencing things (and of course sub elements) and units. A resource can only be referenced from within a policy if the subject creating the policy is also the owner of the resource. Resources have to be declared in the following way:

resources:<things|units>:<non-wildcard-id>[:<optional subelements including wildcards]

Resource definitions not following this pattern will cause Bad Request error response.

Please note that a resource name needs to contain the thing or unit ids - no wildcards are allowed on this level of the resource name.

Examples:

Resourcename  Meaning
resources:things:123 Subject can access the top level thing but not sub elements like components or actions
resources:things:123:* Subject can access all sub elements but not top level thing
resources:things:123:components:lamp:properties:* Subject can only access all the lamp properties
resources:things:123:components:lamp:properties:on Subject can only access all the on property of the lamp
resources:things:123:components:*:properties:on Subject can access all properties with name on
resources:units:123 Subject can access the unit 123

Required scope: connctd.policies.admin or connctd.core

Retrieve policies

Retrieves a list of all policies the subject has created or the subject is referenced by.

Required scope: connctd.policies.read or connctd.core

Request: Method: GET Url: https://api.connctd.io/api/v1/policies

Response: Code: 200 Body: List of policy references. See example below

[
  {
    "href": "https://api.connctd.io/api/v1/policies/1376f734-dbfc-486d-b264-f62d3ff88579"
  }, ...
]

Retrieve policy

Retrieves a single policy.

Required scope: connctd.policies.read or connctd.core

Request: Method: GET Url: https://api.connctd.io/api/v1/policies/-policyid-

Response: Code: 200 Body: Policy. See example below

{
    "id": "f314ca-208a-4fc3-a4d3-4165ce216641",
    "description": "Dummy Policy",
    "subjects": [
        "342244-89ea-45f5-9447-e5c68f567d2b"
    ],
    "resources": [
        "resources:units:f85eb546-e791-4642-86b1-a981678dcf31"
    ],
    "actions": [
        "GET"
    ],
    "effect": "allow",
    "owner": "342ed912-d8d1-430e-aac1-da2e68f33cb6"
}

Delete policy

Removes a policy.

Required scope: connctd.policies.admin or connctd.core

Request: Method: DELETE Url: https://api.connctd.io/api/v1/policies/-policyid-

Response: Code: 200 Body: Empty body

Scopes

Scopes are attached to access tokens and specify the actions that can be performed on resources.

Scope Allows requesting entity to…
connctd.units.read query units
connctd.units.admin create, modify and remove units
connctd.things.read query things
connctd.things.action create actions requests
connctd.connector create, read, modify and remove things
connctd.policies.read query policies
connctd.policies.admin create, modify and remove policies
connctd.core Can’t be requested by oauth 2 apps. Automatically assigend to user token retrieved via /api/v1/auth/login. Combines scopes connctd.policies.read, connctd.policies.admin, connctd.units.admin, connctd.units.read and connctd.things.read

Errors

The connctd.io API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your token or credentials can’t be verified
403 Forbidden – The provided token does not have sufficient permissions for the requested action
404 Not Found – The specified Unit or Thing could not be found
409 Conflict – Resource already exists or conflicts with another resource
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Error response object

{
  "status": "404",
  "error": "THING_DOESNT_EXIST",
  "description": "The requested Thing doesn't exist",
  "more_info": "https://docs.connctd.io/errors/thing_doesnt_exist"
}