GitLab Ai agent identities API

openapi: 3.2.0
info:
  title: GitLab REST Ai agent identities API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Ai agent identities
  description: 'Use this API to register an external agent identity for a project, so that agent

    sessions can be attributed to a user and a machine. Registration returns the existing record if one

    already exists, or is rejected if the identity has been revoked.


    External agents are published through the

    AI Catalog, and act with a

    composite identity that

    combines a service account with the human user who initiated the request.'
  x-displayName: AI agent identities
  externalDocs:
    url: https://docs.gitlab.com/user/duo_agent_platform/composite_identity/
paths:
  /api/v4/projects/{id}/ai_agent/identities:
    post:
      operationId: postApiV4ProjectsIdAiAgentIdentities
      summary: Register an external agent identity
      description: Registers a new agent identity for the current user, project, agent type, and machine fingerprint combination. Returns an existing record if one already exists. Returns 403 if the identity has been revoked.
      tags:
      - Ai agent identities
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesAiExternalAgentsIdentity'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
        example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdAiAgentIdentitiesRequest'
      x-gitlab-lifecycle: experiment
      x-gitlab-tier: premium
components:
  schemas:
    APIEntitiesAiExternalAgentsIdentity:
      type: object
      properties:
        id:
          type: integer
          example: 1
        agent_type:
          type: string
          example: claude-code
        revoked_at:
          type: string
        created_at:
          type: string
          example: '2026-06-17T00:00:00.000Z'
    postApiV4ProjectsIdAiAgentIdentitiesRequest:
      type: object
      properties:
        agent_type:
          type: string
          enum:
          - claude-code
          - opencode
          - cursor
          - codex
          description: Type of agent being registered.
          minLength: 1
        machine_fingerprint:
          type:
          - string
          - 'null'
          description: SHA-256 hash of the machine identifier.
          maxLength: 64
      required:
      - agent_type
      - machine_fingerprint
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header