Skip to main content

Create an API token

API tokens allow external services, scripts, or applications to authenticate with Portal APIs. Tokens are typically used for integrations, automation, and service-to-service access.

Who can create API tokens​

You must be a Portal admin to create or update API tokens.

Step 1: Open App Settings​

  1. In your Portal instance, sign in as an admin.
  2. Go to Admin → App Settings.
  3. Scroll down to the External access section.

In this section, you may see existing API access entries that have already been created.

Step 2: Create or select an API access entry​

You can either:

  • Use an existing API access entry that matches your needs, or
  • Create a new API access entry

Each API access entry represents a static API token configuration and defines:

  • Which plugins the token can access
  • Which permissions are granted
  • The intended purpose (subject) of the token
tip

You can create multiple API access entries if you need different scopes or permissions for different integrations.

Step 3: Configure access permissions​

For the selected API access entry, configure the access restrictions carefully:

  • Plugin access: Limit access to only the plugins the integration needs
  • Permissions: Grant only the required permissions (for example, read-only access)
  • Scope: Avoid overly broad access unless absolutely necessary

Following the principle of least privilege helps prevent unintended access and reduces security risk.

info

For more details, see Access Restrictions in the Backstage documentation.

External access configuration modal

Step 4: Generate a secure token value​

The token value itself is never generated or shown by Portal. You must generate it externally.

You can use any secure method or platform you prefer. For example, using Node.js:

node -p 'require("crypto").randomBytes(24).toString("base64")'

Token requirements​

  • Must be at least 8 characters long
  • Must not contain spaces

Step 5: Save the token​

  1. Paste the generated token value into the Secret field.
  2. Store the token securely before saving.
Important

Once saved, the token value cannot be viewed again in Portal. If you lose it, you will need to generate and set a new one.

  1. Click Add Item.
  2. Click Save.
  3. Wait for Portal to reload and apply the new configuration. You should see a confirmation that the new configuration was applied successfully.

Step 6: Use the API token​

Once configured, the token can be used to authenticate API requests.

Include the token in the Authorization header of your requests:

Authorization: Bearer <your-api-token>

You can use the token from any client, such as:

  • curl
  • Scripts
  • Backend services
  • Automation tools

Verify authentication​

If the token is valid and correctly scoped, API requests will succeed.

If the token is:

  • Missing or invalid → the API will return an authentication error (401)
  • Valid but under-scoped → the API may return a permission error (403)

Security best practices​

  • Treat API tokens like passwords
  • Never commit tokens to source control
  • Store tokens in a secure secrets manager
  • Rotate tokens periodically
  • Use separate tokens for different integrations or environments
  • Revoke and replace tokens immediately if compromised