1. Authentication

Each request to API endpoints requires a token that a user can obtain by performing password authentication with scoped authorization.

Send a POST request to https://<controller_hostname>:35357/v3/auth/tokens, where <controller_hostname> is the hostname of the controller node.

To perform administrative actions, authorize in the project admin with the admin’s password. For example:

# curl -i -H 'Content-Type: application/json' -d '
{
  "auth": {
    "identity": {
      "methods": [
        "password"
      ],
      "password": {
        "user": {
          "domain": {
            "id": "default"
          },
          "name": "admin",
          "password": "****"
        }
      }
    },
    "scope": {
      "project": {
        "domain": {
          "id": "default"
        },
        "name": "admin"
      }
    }
  }
}
' https://<controller_hostname>:35357/v3/auth/tokens

If authorization is successful, the response header will contain the token in the X-Subject-Token header. Pass it in the X-Auth-Token header in all requests. For example:

HTTP/1.1 201 CREATED
Date: Wed, 23 Dec 2020 11:30:22 GMT
Server: Apache/2.4.6 (CentOS) OpenSSL/1.0.2k-fips mod_wsgi/3.4 Python/2.7.5
X-Subject-Token: gAAAAA<...>
Vary: X-Auth-Token
x-openstack-request-id: req-b2e837aa-f726-40c7-b82a-0032b1d68c20
Content-Length: 1331
Content-Type: application/json

{
  "token": {
    "is_domain": false,
    "methods": [
      "password"
    ],
    "roles": [
      {
        "id": "df9b349d40664ea6891b2f0ea73fb40d",
        "name": "admin"
      }
    ],
    "expires_at": "2020-12-25T18:46:57.000000Z",
    "project": {
      "domain": {
        "id": "default",
        "name": "Default"
      },
      "id": "ea2dbb0a4dda4430b7211e714736b13b",
      "name": "admin"
    },
    "catalog": [
      {
        "endpoints": [
          {
            "region_id": null,
            "url": "https://<controller_hostname>:35357/v3",
            "region": null,
            "interface": "public",
            "id": "1dc72f33a010417ebbe1a9454f740e5e"
          },
          {
            "region_id": null,
            "url": "https://<controller_hostname>:35357/v3",
            "region": null,
            "interface": "admin",
            "id": "1e3ad4f204dc4ab18cd8a6c78aed84ed"
          }
        ],
        "type": "identity",
        "id": "8324e13c92b64bd4a18689629385e2a6",
        "name": "keystone"
      },
      {
        "endpoints": [
          {
            "region_id": null,
            "url": "https://<controller_hostname>:6556/v1",
            "region": null,
            "interface": "public",
            "id": "2875f61fa0ef47e6a0e980dcfcab69fc"
          },
          {
            "region_id": null,
            "url": "https://<controller_hostname>:6556/v1",
            "region": null,
            "interface": "admin",
            "id": "b326abeff9d243069c0828b2640811a7"
          }
        ],
        "type": "vzapi",
        "id": "5fa464c4950546db973922af06c4eb6d",
        "name": "vzapi"
      }
    ],
    "user": {
      "password_expires_at": null,
      "domain": {
        "id": "default",
        "name": "Default"
      },
      "id": "117888d5a0db48508447fd44cae57a62",
      "name": "admin"
    },
    "audit_ids": [
      "iG66oDejQ-mmda0PdbLMVg"
    ],
    "issued_at": "2020-12-24T18:46:57.000000Z",
    "is_admin_project": true
  }
}

In addition, the response body will list the endpoints.

To execute API calls as a regular user while being authorized as an admin, pass that user’s ID and project ID in the X-Effective-User-ID and X-Effective-Project-ID HTTP headers, respectively. Call /v3/projects and /v3/users to obtain the IDs.

To authorize as a regular user within the scope of that user’s project, pass the user name, password, and the project name (same as the user name). For example:

# curl -i -H 'Content-Type: application/json' -d '
{
  "auth": {
    "identity": {
      "methods": [
        "password"
      ],
      "password": {
        "user": {
          "domain": {
            "id": "default"
          },
          "name": "user1",
          "password": "****"
        }
      }
    },
    "scope": {
      "project": {
        "domain": {
          "id": "default"
        },
        "name": "user1"
      }
    }
  }
}
' https://<controller_hostname>:35357/v3/auth/tokens

Regular users do not need to pass the X-Effective-User-ID and X-Effective-Project-ID HTTP headers.