Skip to main content

Create an External access token

External access tokens, much like an API token, 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 External access tokens​

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

Step 1: Open App Settings​

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

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

Step 2: Create or select an External access entry​

You can either:

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

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

  • Which plugins the token can access
  • Which permissions are granted
  • The intended purpose (subject) of the token, this will also become the name of the entry
tip

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

Step 3: Configure access restrictions​

For the selected External 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 External access 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