Cookies help us deliver our services. By using our services, you agree to our use of cookies.

OAuth Flow

This is a step by step guide on authenticating against our API. A lot of programming languages have OAuth2 libraries that will do most of the work for you. For Ruby there's the oauth2 gem. On top of this there's omniauth which works well with Rails or other Rack based apps. We've written the omniauth_cobot gem which configures omniauth for Cobot. To see it in action also check out our open source apps.

Before you can use OAuth2 with Cobot you have to register your app. You need to know which scopes your app is going to use (these are documented in the API docs). After registering Cobot gives you a client id and secret which you will need to configure your own app.

To start the OAuth2 web flow you send your user to a URL that looks like this:

https://www.cobot.me/oauth/authorize?response_type=code&client_id=<your app's client id>&redirect_uri=https://your-app.com/auth/callback&state=<optional parameter that gets passed back to you>&scope=<space separated scopes>

Note for spaces using a custom domain: To authenticate users for a Cobot space on a custom domain, send them to <custom domain>/oauth/authorize and not to www.cobot.me/oauth/authorize. People using a space with a custom domain aren't necessarily logged in on the cobot.me domain, which would result in them having to log in again when goin through the OAuth flow.

They will be asked to log in and approve your app. After that they are redirected back to your app, specifically to the redirect_uri you provided above. A parameter called code will be added to the URL. You have to extract this for the next step. If you provided a state parameter it will be added as well.

In the final step you need to acquire an access token by sending a POST request to https://www.cobot.me/oauth/access_token. The request body should look like this:

client_id=<your client id>&client_secret=<your secret>&grant_type=authorization_code&code=<the code from the previous step>

Cobot will answer with an access token that is specific to your app, the requested scope and the current Cobot user. You can use the token immediately to make API requests or you can store it in a database for later use (tokens don't expire).

To make API requests you can either send the token as a parameter called access_token or as a header like this: Authorization: Bearer <your access token>.

Desktop or native mobile apps can use our app flow. For this, the app has to collect the email and password from the user and then exchange it for an access token.

POST https://www.cobot.me/oauth/access_token \
  ?scope=<scopes you need, separated by spaces> \
  &grant_type=password \
  &username=<email of the user> \
  &password=<password of the user> \
  &client_id=<client id of your app> \
  &client_secret=<client secret of your app>

Response:

{
  "access_token": "bd18277b3bb5e5e674a6d7a4fc62d6d15b764dd268df84f08cb99a892baf4124"
  "token_type": "bearer"
}

back to index