Getting started overview

This guide provides a rapid onboarding process for Open Collective, focusing on account setup, API key generation, and executing a foundational GraphQL API request. Open Collective facilitates transparent financial management for collectives, primarily in open-source and community-driven initiatives. The platform supports various funding models and provides tools for managing contributions and expenses with transparency features explaining the Open Collective model.

The Open Collective API is built on GraphQL, a query language for APIs that allows clients to request exactly the data they need. This approach can reduce the amount of data transferred and provides flexibility compared to traditional REST APIs learning about GraphQL. Interaction with the API requires authentication using personal access tokens.

Here’s a quick reference for the initial setup:

Step What to do Where
1. Sign Up Create an Open Collective account. Open Collective account creation page
2. Create Collective Establish your collective on the platform. Open Collective create a collective
3. Generate API Key Access developer settings to create a Personal Access Token (PAT). Open Collective API authentication documentation
4. Make First Request Use your PAT to query collective data via the GraphQL API. GraphQL endpoint: https://api.opencollective.com/graphql/v2

Create an account and get keys

To begin using Open Collective, you must first create a user account and then establish a collective. A collective is the central entity on the platform for managing funds, contributors, and expenses defining Open Collective collectives.

1. Sign Up for an Open Collective Account

  1. Navigate to the Open Collective account creation page.
  2. You can sign up using an email address, or authenticate via GitHub or Google. Choosing a social login can streamline the process.
  3. Follow the prompts to verify your email address if you used the email sign-up option.

2. Create Your Collective

After creating your account, you need to create a collective:

  1. Login to your Open Collective account.
  2. Go to the Create a Collective page.
  3. Provide the necessary details for your collective, including its name, a short description, and choose a fiscal host. The fiscal host manages the legal and financial aspects of your collective. Options include Open Collective's own fiscal hosts or bringing your own Open Collective fiscal host information.
  4. Complete the collective creation process. This typically involves agreeing to terms and potentially setting up initial funding goals.

3. Generate a Personal Access Token (PAT)

Open Collective's API uses Personal Access Tokens for authentication. These tokens grant access to your account's data and actions, similar to an API key.

  1. Log in to your Open Collective account.
  2. Navigate to your profile settings. You can usually find this by clicking on your avatar in the top right corner and selecting "Settings" or "Developer Settings" Open Collective API authentication guide.
  3. Look for a section related to "Personal Access Tokens" or "API Keys".
  4. Click "Create new token" or similar.
  5. Provide a descriptive name for your token (e.g., "My First API Integration").
  6. Select the scopes or permissions required for the token. For initial testing, you might need read-only access to your collective's data. Be mindful of the principle of least privilege: grant only the permissions necessary for the task.
  7. Generate the token. Copy the token immediately, as it will often only be displayed once. Store it securely; it functions as a password for API access.

Your first request

With your PAT in hand, you can now make your first GraphQL API call to Open Collective. We'll use a simple query to fetch details about your newly created collective.

GraphQL Endpoint

The Open Collective GraphQL API endpoint is https://api.opencollective.com/graphql/v2.

Example: Fetching Collective Details

This example demonstrates how to fetch the name and slug of your collective using a curl command. Replace YOUR_COLLECTIVE_SLUG with the actual slug of your collective (found in its URL, e.g., https://opencollective.com/your-collective-slug) and YOUR_PERSONAL_ACCESS_TOKEN with the token you generated.


curl -X POST \
  -H "Content-Type: application/json" \
  -H "Personal-Access-Token: YOUR_PERSONAL_ACCESS_TOKEN" \
  --data '{"query":"query Collective($slug: String!) { collective(slug: $slug) { id name slug } }","variables":{"slug":"YOUR_COLLECTIVE_SLUG"}}' \
  https://api.opencollective.com/graphql/v2

Let's break down the components of this request:

  • -X POST: Specifies that this is a POST request, as GraphQL queries are typically sent over POST.
  • -H "Content-Type: application/json": Indicates that the request body is JSON.
  • -H "Personal-Access-Token: YOUR_PERSONAL_ACCESS_TOKEN": This is your authentication header, containing the Personal Access Token.
  • --data '{"query":"...","variables":{"slug":"..."}}': This is the JSON payload containing your GraphQL query and any variables it requires.
  • query Collective($slug: String!) { collective(slug: $slug) { id name slug } }: The GraphQL query itself. It defines a query named Collective that takes a $slug variable of type String! (non-nullable). It then requests the id, name, and slug fields for the collective matching the provided slug.
  • "variables":{"slug":"YOUR_COLLECTIVE_SLUG"}: The variables object, mapping the $slug variable in the query to your collective's slug.

Expected Response

A successful response will return a JSON object similar to this:


{
  "data": {
    "collective": {
      "id": "cjxxxxxxxxxxxxxxxxxxxxxxxx",
      "name": "Your Collective Name",
      "slug": "your-collective-slug"
    }
  }
}

If you receive this, your authentication and API call were successful.

Common next steps

After successfully making your first API call, you can explore more advanced functionalities:

  • Fetch Contributions: Query contributions to your collective to track funding. This involves exploring the contributions field within the collective object Open Collective API examples for contributions.
  • Manage Expenses: Programmatically submit or retrieve expenses for your collective. The API allows for managing the lifecycle of expenses.
  • Update Collective Information: Use mutations to update your collective's profile, such as its description or website.
  • Integrate with Other Services: Connect Open Collective data with other tools using webhooks or direct API integrations. For example, using a platform like Tray.io for Open Collective integrations could help automate workflows.
  • Explore Webhooks: Set up webhooks to receive real-time notifications about events in your collective, such as new contributions or expense submissions Open Collective webhook documentation.
  • Use a GraphQL Client: For more complex queries and development, consider using a GraphQL client library in your preferred programming language (e.g., Apollo Client for JavaScript, Graphene for Python) or a tool like GraphQL Playground.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

  • Check Personal Access Token: Double-check that your Personal-Access-Token header value is correct and hasn't expired. Ensure there are no leading or trailing spaces.
  • Verify Collective Slug: Confirm that the YOUR_COLLECTIVE_SLUG in your request matches the exact slug of your collective. Slugs are case-sensitive.
  • Review Scopes/Permissions: If you're receiving an authorization error (e.g., 403 Forbidden), your Personal Access Token might not have the necessary permissions (scopes) to access the requested data. Go back to your developer settings and ensure the token has at least read access to collective data.
  • JSON Syntax Errors: Ensure your JSON payload is correctly formatted. Even a misplaced comma or quotation mark can cause a parsing error. Online JSON validators can be helpful.
  • Network Issues: Check your internet connection. If using curl, ensure it's installed and configured correctly in your environment.
  • GraphQL Query Syntax: Verify that your GraphQL query is syntactically correct. Minor typos in field names or types can lead to errors. The Open Collective API reference provides details on available queries and schemas.
  • Rate Limiting: While unlikely for a first call, be aware that APIs often have rate limits. If you make too many requests in a short period, you might temporarily be blocked.
  • Server Status: Check the Open Collective status page (if available) to see if there are any ongoing platform issues.
  • Error Messages: Carefully read any error messages returned in the API response. They often provide specific clues about what went wrong. For example, a GraphQL error might indicate an issue with your query syntax, while an HTTP status code like 401 Unauthorized points to an authentication problem.