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. An access token for testing purposes is created when you register. If you ever need to find your access token again, return to the oauth2_clients page and click the name of your app. You need to know which scopes your app is going to use (these are documented in the API docs). After you register, Cobot gives you a client id and secret which you will need to configure your own app.
To start the OAuth2 web flow, 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 apps running in an iframe on Cobot, in the context of a space: Send the user to <space subdomain>.cobot.me/oauth/authorize and not to www.cobot.me/oauth/authorize.
This will make sure OAuth happens on the space's sudomain or custom domain if one is set up. 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 going 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"
}