API Access

If you're a paid Portabella subscriber (this includes both the Personal and Business plans) you'll have access to the Portabella API. This enables programmatic access to Portabella.

In Portabella API keys are scoped to a project, so if you're looking to interact with multiple projects you'll have to generate an API key for each one.

Portabella exposes a REST API at https://backend.portabella.io. All requests should be sent there.

Get an API key#

Step one is to login to Portabella and navigate to the Integrations tab of your project of choice.

api

Permissions#

After clicking the New integration button you'll be prompted for some information. Put something descriptive for the name of the integration but take care when choosig the permissions you want for your key.

The Writer role will only allow you to write to a project, you will never be able to read project data.

The Reader role will only allow you to read from a project, you will never be able to write project data.

The Project Admin role will allow you to read and write from a project. We urge you to carefully consider what permissions an integration needs before assigning it this role. If your token is leaked any malicious actor will have full access to your data.

Copy token#

After clicking submit you'll be shown a screen asking you to copy the API token.

important

Portabella does not save this so if you lose it it's gone forever.

Usage#

Now that you have the API key any requests to the Portabella API must include a signature with this key. Every request should include the following headers:

  • public-key the corresponding public key to this token
  • challenge a UNIX timestamp not older than 5 minutes
  • signature a signature over the challenge.