The Cobot API is a way to personalize the functionality of our software by extending most of Cobot’s features and giving you access to all of your data. Whether you’re interested in advanced door access functionality, a custom mobile app, or an automated coffee bot, our API is the jumping-off point for enabling the unique creativity and solutions that our customers bring to the table.
Our REST API gives you access to most of Cobot’s features. If you need more endpoints let us know.
The Cobot API is a RESTful API, where resources can be accessed by their URLs. All data is returned as JSON. When you POST or PUT data to the API we expect either form-encoded data or JSON with the appropriate content type header (application/json). Publicly available information can be accessed without any authentication. For private information you have to authenticate using OAuth 2.
If you have problems accessing our API, again, please ask us.
As a starting point take a look at the source code of our example applications on Github.
You can try out most of these apps from the add-ons directory.
To build user interface that integrate with Cobot take a look at our Bots – this is a way to build add-ons using client-side JavaScript only. You get OAuth and a few other things for free.
OAuth is "an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.". "OAuth 2.0 is the next evolution of the OAuth protocol […] OAuth 2.0 focuses on client developer simplicity […] It is supported by many popular sites such as Facebook and there are client libraries available for many programming languages.
For information about OAuth2 see the oauth website.
For OAuth2 you need a client id and secret. In order to get those you have to register your application.
OpenID Connect is a "simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner."
In short, OpenID Connect adds an OAuth2 scope openid. When this is added to the OAuth request, the access token response includes an id token in addition to the access token. The id token is a signed JSON Web Token that includes information about the authenticated user, such as their id, and optionally their email (via additional claims).
For now, Cobot only supports the core and the Provider Configuration Information specifications.
Our provider configuration is available under /.well-known/openid-configuration.
OpenID Connect can also be used under a space’s subdomain. In this case, additional claims are supported.
The provider configuration for a space (<subdomain>.cobot.me/.well-known/openid-configuration) returns the extended claims
as well as OAuth authorization/token endpoints for the space. When these endpoints are used, the id token includes the
name, picture and phone number of the membership of the current user in the space.
OAuth2 defines scopes to restrict access to certain resources.
The required scope for each resource can be found within the documentation for each endpoint.
Please note that a user’s scope can be limited when they access the API as an admin of a space and some of their admin permissions have been revoked.
In general, the rate limit for an endpoint is 60 requests per minute per user. If applicable, alternative limits are given in the documentation for particular endpoints.
If you’ve exceeded the limit, Cobot will return a 429 status code and a JSON error message. The response will also contain a Retry-After header, this denotes the number of seconds to wait before your client may retry.
We have a changelog for the API, so you can keep up to date.
