Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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
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.
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.
ImportantOnce 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