API Authentication

In order to call the HacknPlan API, you first need to authenticate (prove who you are) and be authorized (determine if you are allowed to perform the call). This is similar to logging in to use the web application, but for the API: we need to verify your credentials.

API Keys

In this version of the API, we only provide one authentication and authorization method, which is called API Key. An API Key is something like a combination of user and password, an auto-generated long and complex token that is linked to your user account, so you can identify yourself in API calls using that token.

You can generate an API Key from your user settings page in HacknPlan. Click on your avatar and then Settings, and when the page is loaded select “API” from the left menu. Click on “Create” on the header of the panel to generate a new API Key. 

You need to enter a label for the API Key, which is very useful to identify it in case you generate more that one. We recommend you enter a label that clearly exposes the purpose of the API key, like the name of a script you are using, or the name of another application that requires a key for an integration…

Scopes

During creation, you need to enable or disable certain scopes for the API Key. What are scopes? As we mentioned before, this API Key not only identifies you in the API call (authentication) but also determines which endpoints you are allowed to call (authorization), based on the purpose of this key. Scopes allow you to decide which groups of endpoints are available to whoever uses this key, and which aren’t. This is especially useful when you use this key with a 3rd party that integrates with HacknPlan instead of directly for yourself, and you don’t want to allow them to perform operations you don’t want or need.

The available scopes are the following:

• Workspaces Read: Read the information of the workspace, such as projects, users, teams…
• Workspaces Admin: Invite users, import projects…
• Projects Read: Read all the projects of the user and its data, like name, description, boards, milestones, categories, stages… except for work items and design elements that require their own scope.
• Projects Admin: Modify all the project data that is only available to admins like boards, milestones, stages, roles… 
• Work Items Read: Read the work items of a project.
• Work Items Write: Create, modify or delete the work items of a project.
• Design Model Read: Read the design model of a project.
• Design Model Write: Create, modify or delete the design model of a project.

Note that these scopes authorize you to call the related endpoints, but the permissions of each user within a project or workspace still apply. For instance, if you create an API Key with the Project Admin scope and try to call an endpoint to delete a board without being an admin of the project, it will throw an authorization error. On the other hand, even if you are an admin of the project, if you call that endpoint with an API Key not containing that scope, it will fail.

Using the API Key

Once you have entered a label and set your scopes, you can generate the API Key.

Important: For security reasons, the API Key is only shown right after creation, but it won’t be accessible through the HacknPlan UI after that. For that reason, you need to copy and store it somewhere safe.

The generated API Key should be sent along with the request using the Authorization header:

Key: Authorization

Value: ApiKey {yourApiKey}

Revoking API Keys

Your API Keys do not expire but can be manually revoked. This is useful in case you don’t need the key anymore, or maybe if you detect some unusual activity and prefer to revoke it for security reasons.

You can revoke your API Key from Settings -> API, clicking on the Revoke button next to the API Key entry. API calls using this key will no longer be authenticated.