🚨 This documentation is out of date.
View our New Documentation!
Open Collective Docs
Go back to Open Collective
  • Welcome
  • About
    • Introduction
    • Documentation
    • Terminology
    • Company
    • Pricing
    • Team
    • The Open Collective Way
      • Mission and Values
      • Community Guidelines
    • Hiring
    • Investors
    • Contributing
    • Refund Policy
    • Contact Us
  • Product
    • Features
    • Roadmap
    • Comparison
    • User Profile
    • Dashboard
      • Preview Features
    • Currencies
    • Log-in System
    • Privacy Policy
    • Moderation
    • Security
    • Ledger
      • Individual Transactions
      • Transaction Pairs, Groups & Perspectives
      • Viewing Transactions
      • Exporting Transactions
      • Fiscal Host Ledger Perspective
      • Contributions in the Ledger
      • Added Funds in the Ledger
      • Expenses in the Ledger
      • Ledger Changelog
    • Notifications
    • Two-factor Authentication
    • Activity Log
  • Collectives
    • Collectives FAQ
    • Creating a Collective
    • Quick Start Guide
    • Collective Settings
      • Customize Collective
      • Team
      • Collective Goals & Tiers
      • Expense Policy
      • Data Export
      • Security
      • Integrations
      • Zero Collective Balance
      • Closing a Collective
    • Add Fiscal Host
    • Change Fiscal Host
    • Open Source Collectives
      • Setting up GitHub Sponsors
    • Transparent Budget
    • Expenses
    • Updates & Comms
    • Custom Email
    • Moderation
    • Conversations
    • Events
    • Projects
    • Funding Options
    • Buttons & Banners
    • Connected Collectives
    • Contribution flow
  • Financial Contributors
    • Financial Contributors FAQ
    • Guest contributions
    • Payments
    • Platform Tips
    • Website Badge
    • Receipts
    • Collective to Collective
    • Organizations
      • Organization FAQ
      • Funds
      • Bulk Transfers
      • Gift Cards
      • Sustainer Resources
  • Expenses & Getting Paid
    • Expenses FAQ
    • Submitting Expenses
      • Inviting a third-party to submit an Expense
    • Expense Comments
    • Edit or Download an Expense
    • Receiving payment through Payoneer or Wise
    • Tax Information
  • Fiscal Hosts
    • Fiscal Hosts FAQ
    • Becoming a Fiscal Host
    • Creating a Fiscal Host
    • Organisation Settings
      • Info
      • Customize Profile Page
      • Connect external accounts
      • Accounting Categories
      • Security
      • Manage updates
      • Policies
    • Fiscal Host Dashboard
      • Expenses
      • Financial contributions
      • Pending applications
      • Hosted Collectives
      • Vendors
      • Transaction Report
        • Reports
    • Receiving Money
      • Bank Transfers
      • Credit Card
      • Add Funds Manually
      • Expected Funds
    • Payouts
      • Virtual Card Settings
      • Payouts with PayPal
      • Payouts with Wise
      • Two-factor authentication for payouts
      • Refunds
    • Host Fees
    • Local Tax Support
    • Agreement Templates
  • Independent Collectives
    • About Independent Collectives
    • Create an Independent Collective
      • Migrate from Self-Hosted to Independent Collective
      • Migrate from a Fiscal Host to Independent Collective
    • Independent Collective Setup
    • Independent Collective Management
      • Money coming in: Contributions
      • Money going out: Expenses
    • Close an Independent Collective
  • Contributing
    • Design
      • Design Workflow
      • Design Contribution Guidelines
    • Development
      • Contribution Guide
      • Best Practice Guidelines
      • Bounties
      • Architecture
      • API
        • Members
        • Collectives
        • Events
      • README Integration
      • PayPal
      • TransferWise
      • Post-Donation Redirect
      • Manual Reporting
      • GitHub Permissions
      • Internationalization (i18n) system
      • Testing with Cypress
      • Testing features
        • Conversations
      • Collective's locations
      • Virtual Cards
    • Documentation
      • Resources for documentarians
      • Style guide
      • Suggesting changes
    • Translation
  • Developers
    • OAuth
    • Personal Tokens
Powered by GitBook

Helpful Links

  • Website
  • Blog
  • Contact
  • Slack

â’¸ Open Collective 2024

On this page
  • Creating an OAuth app
  • Authorizing OAuth apps
  • 1. Request a user's Open Collective identity
  • 2. Users are redirected back to your site
  • 3. Use the access token to access the API
  • Scopes for OAuth apps
  • Available scopes
  • About 2FA

Was this helpful?

Edit on GitHub
Export as PDF
  1. Developers

OAuth

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

PreviousDevelopersNextPersonal Tokens

Last updated 10 months ago

Was this helpful?

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. Click on + Create OAuth app and fill in the required information

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

Authorizing OAuth apps

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

Parameters

Name
Type
Description

client_id

string

response_type

string

Required. Only supported value for now is code

redirect_uri

string

The URL in your application where users will be sent after authorization. If left out, Open Collective will redirect users to the callback URL configured in the OAuth Application settings. If provided, the redirect URL's host and port must exactly match the callback URL.

scope

string

A comma-separated list of scopes. If not provided, scope defaults to an empty list.

state

string

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:

Parameters

Parameter
Type
Description

grant_type

string

Required. The only supported value for now is authorization_code

client_id

string

client_secret

string

code

string

redirect_uri

string

Required. The URL in your application where users are sent after authorization.

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

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:

Open Collective's OAuth implementation supports the standard .

GET

Required. The client ID you copied after .

Use it to pass some state back to your application after redirecting and to protect against cross-site request forgery attacks (CSRF) by including an unguessable random string. See .

POST

Required. The client ID of your OAuth application (from )

Required. The client secret of you OAuth application (from )

Required. The code you received as a response to , after the redirect)

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 (in the #api channel) or , and we'll enable it manually.

authorization code grant type
https://opencollective.com/oauth/authorize
https://opencollective.com/oauth/token
Discord
contact support
creating your app
scopes below
Creating an OAuth App
Creating an OAuth App
Step 1
Connect OAuth app authorization screen
Authorized apps screen