Skip to main content

​
Overview

All Xloud 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 Xloud 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" }
        }
      }
    }
  }'
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.

Navigate to Application Credentials

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

Configure the credential

FieldValueDescription
Nameci-deploy-prodDescriptive identifier
SecretAuto-generated or customStore this immediately — it is shown only once
ExpirationOptional dateLeave blank for non-expiring credentials
RolesmemberRestrict to minimum required roles
UnrestrictedDisabledOnly 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 Xloud CLI and Python SDK.
The clouds.yaml file is saved to your local machine and can be placed at ~/.config/xloud/clouds.yaml.

​
Scoped Tokens

Tokens can be scoped to different resources depending on the operation required:
ScopeUse CaseRequest scope field
Project-scopedManage resources within a project"project": { "name": "myproject" }
Domain-scopedManage users and projects within a domain"domain": { "name": "Default" }
System-scopedAdministrative operations across all projects"system": { "all": true }
UnscopedDiscover available projects before scopingOmit 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

OperationEndpointMethod
Create token/identity/v3/auth/tokensPOST
Validate token/identity/v3/auth/tokensGET (with X-Subject-Token)
Revoke token/identity/v3/auth/tokensDELETE (with X-Subject-Token)
List tokens (admin)/identity/v3/OS-PKI/revokedGET
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 Xloud Dashboard → Project → API Access → Download OpenStack RC File.

​
Troubleshooting

Cause: Token is expired, invalid, or not included in the request header.Resolution:
  1. Re-authenticate to obtain a fresh token
  2. Confirm the token is passed in X-Auth-Token (not Authorization: Bearer)
  3. Verify the Identity endpoint URL is correct
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.
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

Automation Guide

Scripting patterns and token refresh strategies for automation

Application Credentials

Create and manage application credentials for non-interactive access