> ## 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.

> Generate API tokens in Portal App Settings for external services, scripts, and automation to authenticate with Portal APIs.

# Create api key

# 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.
</Tip>

## 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](https://backstage.io/docs/auth/service-to-service-auth/#access-restrictions)
  in the Backstage documentation.
</Info>

<Frame>
  <img
    src="https://mintcdn.com/spotify-89f50c35/85h6d6JBwbSgiyqH/portal/assets/admin-external-access-modal.png?fit=max&auto=format&n=85h6d6JBwbSgiyqH&q=85&s=65aaf89624c631b4d36f4f5fedb00d25"
    alt="External access configuration
modal"
    width="4112"
    height="2152"
    data-path="portal/assets/admin-external-access-modal.png"
  />
</Frame>

## 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:

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
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.

<Warning>
  **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.
</Warning>

3. Click **Add Item**.
4. Click **Save**.
5. 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:

```http theme={"theme":{"light":"github-light","dark":"dracula"}}
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