OAuth

OAuth lets you create applications that can access Open Collective's API to read information and trigger changes on the platform.

Creating an OAuth app

  1. Go to https://opencollective.com/{account}/admin/for-developers (replace {account} by the slug of the account you want to use as the owner of the app)

  2. On the success page, copy the client ID and secret for later use

Authorizing OAuth apps

Open Collective's OAuth implementation supports the standard authorization code grant type.

The web application flow to authorize users for your app is:

  1. Users are redirected to request their Open Collective identity

  2. Users are redirected back to your site by Open Collective with special code shared in the URL

  3. You exchange the received code for an OAuth token

1. Request a user's Open Collective identity

GET https://opencollective.com/oauth/authorize

Parameters

2. Users are redirected back to your site

After users accept your request, they're redirected back to your site with a temporary code passed as an URL query parameter as well as the state you provided in the previous step. The temporary code will expire after 5 minutes. If the states don't match, then a third party created the request, and you should abort the process.

Otherwise, you can exchange the code you received as a parameter for an access token:

POST https://opencollective.com/oauth/token

Parameters

Response

If the request succeeds, you'll receive an HTTP 200 response code with a JSON payload like:

{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

This access_token is what you want to use to access the API.

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user on our public GraphQL API.

Authorization: Bearer {ACCESS_TOKEN}
GET https://opencollective.com/oauth/token

For example, in curl you can set the Authorization header like this:

curl 'https://opencollective.com/api/graphql/v2' \
  -H 'authorization: Bearer {ACCESS_TOKEN}' \
  -H 'content-type: application/json' \
  -d '{"query": "{ me { id name email } }"}'

Scopes for OAuth apps

Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.

When setting up an OAuth App on Open Collective, requested scopes are displayed to the user on the authorization form.

Available scopes

  • email: Access your email address.

  • incognito: Access your incognito account.

  • account: Manage your account, collectives and organizations.

  • expenses: Create and manage expenses, payout methods.

  • orders: Create and manage contributions, payment methods.

  • transactions: Refund and reject recorded transactions.

  • virtualCards: Create and manage virtual cards.

  • updates: Create and manage updates.

  • conversations: Create and manage conversations.

  • webhooks: Create and manage webhooks

  • host: Administrate fiscal hosts.

About 2FA

By default, OAuth apps are not allowed to use Two Factor Authentication (2FA) and thus cannot use protected queries and mutations (e.g. payExpense, removeHost, ...etc.) for accounts with 2FA setup. If your app needs these permissions, reach out to us on Discord (in the #api channel) or contact support, and we'll enable it manually.

Once allowed for 2FA, your app will show a special message for users connecting with 2FA to let them know that they're giving this special permission:

To know whether the 2FA permission has been granted to your app, go to the application settings in your workspace and look for the warning at the top:

Last updated

Ⓒ Open Collective 2024