Skip to content

Authentication

Overview

Changemap's API is meant to be used for automated, programmatic access to your roadmap. To this end, we provide a token-based authentication scheme. Team members can create multiple tokens, where each named token has access to only one map and acts as a "bot" account. Its activity is visible to team members and end users like any other team member's. Anticipated use cases are integrations with other services, such as an internal task management tool, where the bot can add and update tasks to match internal status. Tokens do not expire.

Token scope can be read-only, read and write, and read, write, and manage:

  • Read-only tokens can see all data about their maps;
  • Read and write tokens can also add, edit, and delete tasks, comments, and votes, similar to the team member "moderator" role;
  • Read, write, and manage tokens can also edit and delete the map description and map lists.

All endpoints require authentication. Make sure this token is included in your requests by including the Authorization header with every request.

If you are logged in to Changemap in the browser your session-based authentication will also work. This is handy for browsing the API in read-only mode (assuming you've set up your browser to accept JSON) but shouldn't be relied on for programmatic access.

Create a token

Open your roadmap and click the "Manage" button under the welcome message. From the sidebar menu, choose "API Tokens".

(If you're not on a paid plan, this option won't be available to you, and you'll need to upgrade. You can do this from the management page for your team account — click your team name in the sidebar menu, or in your profile details on your account page.)

Here's an example for a map called Exist:

Create tokens form

Tokens are listed here and visible to all team members with the "admin" role. Multiple tokens can be created.

Sign requests

Include the Authorization: Token [your_token] header in all requests.

# With curl, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: Token 96524c5ca126d87eb18ee7eff408ca0e71e94737"

import requests

requests.get(url,
    headers={'Authorization':'Token 96524c5ca126d87eb18ee7eff408ca0e71e94737'})