API Authentication

Overview

All OpenStack API requests require a valid bearer token in the X-Auth-Token request header. The Identity service (Keystone) issues tokens upon successful authentication. Tokens are time-limited, project-scoped, and carry the role assignments of the authenticated user.

Prerequisites

An active Polystack account
Project name, username, and password (or application credential ID and secret)
Identity endpoint: https://api.<your-domain>/identity/v3

Token-Based Authentication

Password Authentication

Authenticate with a username and password to receive a project-scoped token:

curl -i -X POST https://api.<your-domain>/identity/v3/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "identity": {
        "methods": ["password"],
        "password": {
          "user": {
            "name": "myuser",
            "domain": { "name": "Default" },
            "password": "mypassword"
          }
        }
      },
      "scope": {
        "project": {
          "name": "myproject",
          "domain": { "name": "Default" }
        }
      }
    }
  }'

import requests

auth_payload = {
    "auth": {
        "identity": {
            "methods": ["password"],
            "password": {
                "user": {
                    "name": "myuser",
                    "domain": {"name": "Default"},
                    "password": "mypassword"
                }
            }
        },
        "scope": {
            "project": {
                "name": "myproject",
                "domain": {"name": "Default"}
            }
        }
    }
}

resp = requests.post(
    "https://api.<your-domain>/identity/v3/auth/tokens",
    json=auth_payload
)
token = resp.headers["X-Subject-Token"]
print(f"Token: {token}")

The response contains:

X-Subject-Token header — the token string to use in subsequent calls
JSON body with token metadata including expiry time and service catalog

Token metadata response (excerpt)

{
  "token": {
    "expires_at": "2026-03-19T10:00:00.000000Z",
    "issued_at": "2026-03-18T10:00:00.000000Z",
    "methods": ["password"],
    "project": {
      "id": "abc123",
      "name": "myproject",
      "domain": { "id": "default", "name": "Default" }
    },
    "roles": [
      { "id": "def456", "name": "member" }
    ],
    "catalog": [...]
  }
}

Application Credentials

Application credentials allow services and automation scripts to authenticate without exposing user passwords. They are scoped to a specific project and role set at creation time.

Dashboard
CLI

Navigate to Application Credentials

Log in to the Polystack Dashboard (https://connect.<your-domain>) and navigate to Project → Identity → Application Credentials. Click Create Application Credential.

Configure the credential

Field	Value	Description
Name	`ci-deploy-prod`	Descriptive identifier
Secret	Auto-generated or custom	Store this immediately — it is shown only once
Expiration	Optional date	Leave blank for non-expiring credentials
Roles	`member`	Restrict to minimum required roles
Unrestricted	Disabled	Only enable if the credential must manage other credentials

Copy the Secret value immediately after creation. It cannot be retrieved again. If lost, delete and recreate the credential.

Download the clouds.yaml

Click Download clouds.yaml to get a ready-to-use configuration file for the Polystack CLI and Python SDK.

The clouds.yaml file is saved to your local machine and can be placed at ~/.config/polystack/clouds.yaml.

Create an application credential

openstack application credential create ci-deploy-prod \
  --role member \
  --description "CI/CD deployment credential for production project"

Store the secret value from the output immediately.

Authenticate using an application credential

curl -i -X POST https://api.<your-domain>/identity/v3/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "identity": {
        "methods": ["application_credential"],
        "application_credential": {
          "id": "<credential-id>",
          "secret": "<credential-secret>"
        }
      }
    }
  }'

Scoped Tokens

Tokens can be scoped to different resources depending on the operation required:

Scope	Use Case	Request `scope` field
Project-scoped	Manage resources within a project	`"project": { "name": "myproject" }`
Domain-scoped	Manage users and projects within a domain	`"domain": { "name": "Default" }`
System-scoped	Administrative operations across all projects	`"system": { "all": true }`
Unscoped	Discover available projects before scoping	Omit the `scope` field

Exchange an Unscoped Token for a Project-Scoped Token

Step 1: Obtain unscoped token

curl -i -X POST https://api.<your-domain>/identity/v3/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "identity": {
        "methods": ["password"],
        "password": {
          "user": {
            "name": "myuser",
            "domain": { "name": "Default" },
            "password": "mypassword"
          }
        }
      }
    }
  }'

Step 2: List available projects

curl -X GET https://api.<your-domain>/identity/v3/auth/projects \
  -H "X-Auth-Token: $UNSCOPED_TOKEN"

Step 3: Exchange for project-scoped token

curl -i -X POST https://api.<your-domain>/identity/v3/auth/tokens \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $UNSCOPED_TOKEN" \
  -d '{
    "auth": {
      "identity": {
        "methods": ["token"],
        "token": { "id": "'"$UNSCOPED_TOKEN"'" }
      },
      "scope": {
        "project": { "id": "<project-id>" }
      }
    }
  }'

Token Lifecycle

Operation	Endpoint	Method
Create token	`/identity/v3/auth/tokens`	POST
Validate token	`/identity/v3/auth/tokens`	GET (with `X-Subject-Token`)
Revoke token	`/identity/v3/auth/tokens`	DELETE (with `X-Subject-Token`)
List tokens (admin)	`/identity/v3/OS-PKI/revoked`	GET

Validate a token

curl -i -X GET https://api.<your-domain>/identity/v3/auth/tokens \
  -H "X-Auth-Token: $OS_TOKEN" \
  -H "X-Subject-Token: $TOKEN_TO_VALIDATE"

Revoke a token

curl -i -X DELETE https://api.<your-domain>/identity/v3/auth/tokens \
  -H "X-Auth-Token: $OS_TOKEN" \
  -H "X-Subject-Token: $TOKEN_TO_REVOKE"

Tokens expire after the configured token TTL (default: 1 hour). Long-running automation scripts should implement token refresh logic — detect 401 Unauthorized responses and re-authenticate automatically.

Using the OpenRC File

For CLI and script use, source an OpenRC credentials file instead of manually passing credentials:

Source OpenRC file

source admin-openrc.sh

Sample OpenRC file content

export OS_AUTH_URL=https://api.<your-domain>/identity/v3
export OS_PROJECT_NAME=myproject
export OS_USERNAME=myuser
export OS_PASSWORD=mypassword
export OS_USER_DOMAIN_NAME=Default
export OS_PROJECT_DOMAIN_NAME=Default
export OS_IDENTITY_API_VERSION=3

Download the OpenRC file from Polystack Dashboard → Project → API Access → Download OpenStack RC File.

Troubleshooting

401 Unauthorized on every request

Cause: Token is expired, invalid, or not included in the request header.Resolution:

Re-authenticate to obtain a fresh token
Confirm the token is passed in X-Auth-Token (not Authorization: Bearer)
Verify the Identity endpoint URL is correct

403 Forbidden despite valid token

Cause: The token is valid but the user’s role does not permit this operation.Resolution: Verify your role assignment in the project:

Check role assignments

openstack role assignment list --user $OS_USERNAME --project $OS_PROJECT_NAME

Contact your administrator to assign the appropriate role.

Token scope mismatch

Cause: The token is scoped to a different project than the resource being accessed.Resolution: Re-authenticate with the correct project scope. Confirm the OS_PROJECT_NAME environment variable matches the project containing the resource.

Next Steps

Compute API

Launch and manage instances using the Compute API

Identity API

Manage users, projects, and roles via the Identity API

Application Credentials

Create and manage application credentials for non-interactive access

Core Services

Other Services

Overview

Token-Based Authentication

Password Authentication

Application Credentials

Navigate to Application Credentials

Configure the credential

Download the clouds.yaml

Scoped Tokens

Exchange an Unscoped Token for a Project-Scoped Token

Token Lifecycle

Using the OpenRC File

Troubleshooting

Next Steps

Compute API

Identity API

Application Credentials

​Overview

​Token-Based Authentication

​Password Authentication

​Application Credentials

Navigate to Application Credentials

Configure the credential

Download the clouds.yaml

​Scoped Tokens

​Exchange an Unscoped Token for a Project-Scoped Token

​Token Lifecycle

​Using the OpenRC File

​Troubleshooting

​Next Steps

Compute API

Identity API

Application Credentials

Overview

Token-Based Authentication

Password Authentication

Application Credentials

Scoped Tokens

Exchange an Unscoped Token for a Project-Scoped Token

Token Lifecycle

Using the OpenRC File

Troubleshooting

Next Steps