API Keys

An API Key serves the purpose of authenticating a user or program to an API (application programming interface). The Northflank API uses JSON Web Tokens (JWT) as authentication keys. Keys can be issued with different levels of authorization defining which resources in the API the user can access and which operations can be performed on those resources, e.g. resource Projects, permission Read.

Northflank API Keys apply across Projects by default, but can be restricted to a specific Project.

In the following sections, we explain how API Keys differ for Users and Teams.

User API Keys

Users can create an unlimited amount of API Keys with different permissions. To create a new Key:

  1. Visit the API Keys tab in your Account settings
  2. Click Create API Key
  3. Enter a Key name
  4. Select the desired operations (Create, Read etc.) for the available resources (Services etc.) by clicking the buttons. To select all operations for a resource use the Select all control.
  5. If you wish to restrict the token to a Project, click the green toggle marked Unrestricted and choose a Project from the dropdown.
  6. Finish by clicking Create API key
Create user API key

The API Key will now appear in the list on the API Keys tab. You can copy the JWT to clipboard by clicking on the value in the Key Token column. For instructions on how to use the JWT, please visit the API docs.

Controls to the right of each list item allow you to view the permissions assigned to the Key or to delete it.

Team API Keys

Team API Keys require some setup before they can be created. You have to first define an API Key Template which will allow Team members to create API Keys based on that Template.

API Key Templates

API Key Templates come with the same permission management as User API Keys. Additionally, the creator has to define which Team members have permission to create Keys based on the Template.

Creating a Template

To create an API Key Template:

  1. Visit the API Key Templates tab in your Team settings
  2. Click Create API Key Template
  3. Enter a Template Name and Description
  4. Select the desired operations (Create, Read etc.) for the available resources (Services etc.) by clicking the buttons. To select all operations for a resource use the Select all control.
  5. If you wish to restrict the Template to a Project, click the green toggle marked Unrestricted and choose a Project from the dropdown.
  6. Choose the Team members with access to the token from the Members with access checklist
  7. Click Create API Key Template
Create team API key template

The template will appear in the menu in the left of the API Key Templates tab.

Edit a Template

To edit a Template:

  1. Visit the API Key Templates tab in your Team settings
  2. Select the Template from the list in the left of the tab
  3. Modify any aspect of the Template, the same as during Template creation
  4. Click Update

To delete the Template, click the Delete template button in the top right of the tab. This will instantly remove all user keys created with the Template.

Create a Team API Key

To create a Team API Key from the API Keys tab:

  1. Click the button Create API Key in the top right corner of the tab
  2. Enter a Token name
  3. Find the appropriate Template in the list and click its Create button
Create team API key

The API Key will now appear in the list on the API Keys tab. You can copy the JWT to your clipboard by clicking on the value in the Key Token column. For instructions on how to use the JWT, please visit the API docs.

Controls to the right of each list item allow you to view the permissions assigned to the Key or to delete it.

© 2020 Northflank Ltd. All rights reserved.

TermsPrivacy

contact@northflank.com