OAuth lets you create applications that can access Open Collective's API to read information and trigger changes on the platform.
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)
On the success page, copy the client ID and secret for later use
Open Collective's OAuth implementation supports the standard authorization code grant type.
The web application flow to authorize users for your app is:
Users are redirected to request their Open Collective identity
Users are redirected back to your site by Open Collective with special code shared in the URL
You exchange the received code for an OAuth token
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:
If the request succeeds, you'll receive an HTTP 200 response code with a JSON payload like:
This access_token
is what you want to use 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.
For example, in curl you can set the Authorization header like this:
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.
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.
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:
Click on + Create OAuth app
and fill in the required information
Name | Type | Description |
---|---|---|
Parameter | Type | Description |
---|---|---|
client_id
string
Required. The client ID you copied after creating your app.
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
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 scopes below.
grant_type
string
Required. The only supported value for now is authorization_code
client_id
string
Required. The client ID of your OAuth application (from Creating an OAuth App)
client_secret
string
Required. The client secret of you OAuth application (from Creating an OAuth App)
code
string
Required. The code you received as a response to Step 1, after the redirect)
redirect_uri
string
Required. The URL in your application where users are sent after authorization.
Personal tokens are used to authenticate with the Open Collective API. They are not tied to a specific application and can be used for various purposes, such as automating tasks or integrating with other services. To use a personal token, you can pass it as a Personal-Token
HTTP header or as a personalToken
query parameter in the URL.
If your goal is to have other users authenticating with your app/script, you should look into OAuth rather than personal tokens.
To create a personal token, follow these steps:
Go to your Open Collective account workspace.
Navigate to the "For developers" section.
Click on the "Create Personal Token" button.
Enter a name for your personal token and select the scopes you want it to have.
Optionally tick the checkbox for "Advanced privileges" if you want your token to be able to call queries and mutations that require 2FA (see ).
Optionally set an expiration date.
Click on the "Create token" button.
Everything you set here can be later changed from the token settings page.
Once you have created a personal token, you can use it to authenticate with the Open Collective API. To do this, you can pass the token as a Personal-Token HTTP header or as a personalToken
query parameter in the URL. For example, the following URL would use the personal token "my-token" to make a GET request to the /graphql endpoint:
Personal tokens support the same scopes as OAuth apps. Scopes determine what actions a personal token can perform. You can find a complete list of scopes in the OAuth documentation.
The "Allow this token to directly use operations that would normally require 2FA" checkbox allows you to grant your personal token the ability to perform certain actions that would normally require two-factor authentication (2FA). This can be useful for automating tasks that require access to sensitive data, such as processing expenses. However, it is important to note that granting this privilege increases the security risk if your personal token is compromised.
Personal tokens can be used for a variety of purposes, including:
Automating tasks such as creating expenses, managing memberships, or issuing payouts.
Integrating with other services such as accounting software or project management tools.
Developing custom tools and integrations for Open Collective.