openapi: 3.1.0
info:
  title: OpenStack Identity (Keystone) API v3
  description: >-
    Keystone is the OpenStack Identity service that provides authentication,
    authorization, and a service catalog for an OpenStack cloud. Tokens
    issued by Keystone are required to call any other OpenStack service
    API. The v3 API exposes endpoints for tokens, users, groups, projects,
    domains, roles, role assignments, services, endpoints, and the service
    catalog.
  version: '3'
  contact:
    name: OpenStack Identity (Keystone)
    url: https://docs.openstack.org/keystone/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
  description: Keystone v3 API reference
  url: https://docs.openstack.org/api-ref/identity/v3/
servers:
  - url: https://{keystone-host}:5000/v3
    description: Keystone Identity API v3 endpoint (deployment specific)
    variables:
      keystone-host:
        default: keystone.example.com
security:
  - TokenAuth: []
tags:
  - name: Tokens
    description: Issue and validate authentication tokens.
  - name: Users
    description: User management.
  - name: Groups
    description: Group management.
  - name: Projects
    description: Project (tenant) management.
  - name: Domains
    description: Domain management for multi-tenancy.
  - name: Roles
    description: Role definitions and assignments.
  - name: Services
    description: Service catalog entries.
  - name: Endpoints
    description: Service endpoint URLs per region and interface.
paths:
  /auth/tokens:
    post:
      operationId: issueToken
      summary: Issue an authentication token
      description: >-
        Authenticate using credentials (password, application credential, or
        token) and receive a scoped or unscoped token in the X-Subject-Token
        response header along with a service catalog body.
      tags: [Tokens]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
      responses:
        '201':
          description: Token issued.
          headers:
            X-Subject-Token:
              schema:
                type: string
              description: The issued token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
    get:
      operationId: validateToken
      summary: Validate token
      tags: [Tokens]
      parameters:
        - name: X-Subject-Token
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Token is valid.
    head:
      operationId: checkToken
      summary: Check token (no body)
      tags: [Tokens]
      parameters:
        - name: X-Subject-Token
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Token is valid.
    delete:
      operationId: revokeToken
      summary: Revoke token
      tags: [Tokens]
      parameters:
        - name: X-Subject-Token
          in: header
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Token revoked.
  /users:
    get:
      operationId: listUsers
      summary: List users
      tags: [Users]
      responses:
        '200':
          description: List of users.
    post:
      operationId: createUser
      summary: Create user
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User created.
  /users/{user_id}:
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getUser
      summary: Get user
      tags: [Users]
      responses:
        '200':
          description: User detail.
    patch:
      operationId: updateUser
      summary: Update user
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: User updated.
    delete:
      operationId: deleteUser
      summary: Delete user
      tags: [Users]
      responses:
        '204':
          description: User deleted.
  /groups:
    get:
      operationId: listGroups
      summary: List groups
      tags: [Groups]
      responses:
        '200':
          description: List of groups.
    post:
      operationId: createGroup
      summary: Create group
      tags: [Groups]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Group created.
  /projects:
    get:
      operationId: listProjects
      summary: List projects
      tags: [Projects]
      responses:
        '200':
          description: List of projects.
    post:
      operationId: createProject
      summary: Create project
      tags: [Projects]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Project created.
  /projects/{project_id}:
    parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getProject
      summary: Get project
      tags: [Projects]
      responses:
        '200':
          description: Project detail.
    patch:
      operationId: updateProject
      summary: Update project
      tags: [Projects]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Project updated.
    delete:
      operationId: deleteProject
      summary: Delete project
      tags: [Projects]
      responses:
        '204':
          description: Project deleted.
  /domains:
    get:
      operationId: listDomains
      summary: List domains
      tags: [Domains]
      responses:
        '200':
          description: List of domains.
    post:
      operationId: createDomain
      summary: Create domain
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Domain created.
  /roles:
    get:
      operationId: listRoles
      summary: List roles
      tags: [Roles]
      responses:
        '200':
          description: List of roles.
    post:
      operationId: createRole
      summary: Create role
      tags: [Roles]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Role created.
  /role_assignments:
    get:
      operationId: listRoleAssignments
      summary: List role assignments
      tags: [Roles]
      parameters:
        - name: scope.project.id
          in: query
          schema:
            type: string
        - name: scope.domain.id
          in: query
          schema:
            type: string
        - name: user.id
          in: query
          schema:
            type: string
        - name: group.id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Role assignments.
  /services:
    get:
      operationId: listServices
      summary: List services in catalog
      tags: [Services]
      responses:
        '200':
          description: List of services.
    post:
      operationId: createService
      summary: Create service
      tags: [Services]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Service created.
  /endpoints:
    get:
      operationId: listEndpoints
      summary: List service endpoints
      tags: [Endpoints]
      responses:
        '200':
          description: List of endpoints.
    post:
      operationId: createEndpoint
      summary: Create endpoint
      tags: [Endpoints]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Endpoint created.
components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: X-Auth-Token
  schemas:
    AuthRequest:
      type: object
      properties:
        auth:
          type: object
          properties:
            identity:
              type: object
              properties:
                methods:
                  type: array
                  items:
                    type: string
                    enum: [password, token, application_credential]
                password:
                  type: object
                token:
                  type: object
                application_credential:
                  type: object
            scope:
              oneOf:
                - type: object
                  properties:
                    project:
                      type: object
                - type: object
                  properties:
                    domain:
                      type: object
                - type: string
                  enum: [unscoped]
    Token:
      type: object
      properties:
        token:
          type: object
          properties:
            methods:
              type: array
              items:
                type: string
            user:
              $ref: '#/components/schemas/User'
            project:
              type: object
            domain:
              type: object
            roles:
              type: array
              items:
                type: object
            catalog:
              type: array
              items:
                type: object
            expires_at:
              type: string
              format: date-time
            issued_at:
              type: string
              format: date-time
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        enabled:
          type: boolean
        domain_id:
          type: string
        default_project_id:
          type: string
        description:
          type: string
        password_expires_at:
          type: string
          format: date-time