AGNTCY Issuer Service API

openapi: 3.2.0
info:
  title: Identity Node Issuer Service API
  description: Identity Node
  contact:
    name: Agntcy Team
    url: https://github.com/agntcy/identity
    email: identity@agntcy.org
  version: v1alpha1
  x-provenance:
    method: harvested
    authored_by: AGNTCY (Outshift by Cisco)
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: agntcy.org / outshift.com
    note: 'Four first-party machine-readable contracts: the Agent Connect Protocol OpenAPI 3.1.1, the OASF Schema API, and two AGNTCY Identity OpenAPI 3.0.3 documents. schema.oasf.outshift.com is the one genuinely callable AGNTCY-hosted API (unauthenticated, 200).'
  x-evidence:
  - type: source
    url: https://spec.acp.agntcy.org/
  - type: source
    url: https://schema.oasf.outshift.com/doc
  - type: source
    url: https://identity-docs.outshift.com/api/openapi/service/v1alpha1/openapi.yaml
servers:
- url: http://0.0.0.0:4000
  description: Local environment
security:
- {}
tags:
- name: IssuerService
  description: IssuerService is the service that provides ISSUER node operations.
paths:
  /v1alpha1/issuer/register:
    post:
      tags:
      - IssuerService
      description: Register an issuer by providing the issuer details
      operationId: IssuerService_Register
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterIssuerRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterIssuerResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1alpha1/issuer/{commonName}/.well-known/jwks.json:
    get:
      tags:
      - IssuerService
      description: "Returns the well-known document content for an issuer in\n Json Web Key Set (JWKS) format"
      operationId: IssuerService_GetWellKnown
      parameters:
      - name: commonName
        in: path
        description: The common name of the issuer
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetIssuerWellKnownResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    Proof:
      type: object
      properties:
        type:
          type: string
          description: The type of the proof
        proofPurpose:
          type: string
          description: The proof purpose
        proofValue:
          type: string
          description: The proof value
      description: "A data integrity proof provides information about the proof mechanism,\n parameters required to verify that proof, and the proof value itself."
    GetIssuerWellKnownResponse:
      type: object
      properties:
        jwks:
          allOf:
          - $ref: '#/components/schemas/Jwks'
          description: The well-known Json Web Key Set (JWKS) document
      description: Returns the content of the well-known JWKS document
    Jwks:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/Jwk'
          description: Keys represents the list of JSON Web Keys.
      description: JWKS represents a set of JSON Web Keys (JWKs).
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
    Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    RegisterIssuerRequest:
      type: object
      properties:
        issuer:
          allOf:
          - $ref: '#/components/schemas/Issuer'
          description: The Issuer to register.
        proof:
          allOf:
          - $ref: '#/components/schemas/Proof'
          description: "Optional Proof of ownership of the Issuer's common_name\n This should be provided when the Issuer is provided by an external IdP\n Example: a signed JWT"
      description: Request to register an issuer
    RegisterIssuerResponse:
      type: object
      properties: {}
      description: Returns a registration response for the issuer
    Jwk:
      type: object
      properties:
        alg:
          type: string
          description: "ALG represents the algorithm intended for use with the key.\n Example algorithms for Post-Quantum ML-DSA family:\n \"ML-DSA-44\", \"ML-DSA-65\", \"ML-DSA-87\".\n Some example algorithms are \"RS256\", \"RS384\", \"RS512\" for RSA algorithms."
        kty:
          type: string
          description: "KTY represents the key type parameter.\n It specifies the family of quantum algorithms used with the key,\n such as \"AKP\" for post quantum algorithms\n or \"RSA\" for non quantum algorithms."
        use:
          type: string
          description: "Use represents the intended use of the key.\n Some example values are \"enc\" and \"sig\"."
        kid:
          type: string
          description: "KID represents the key ID.\n It is used to match a specific key."
        pub:
          type: string
          description: The public key for the AKP kty.
        priv:
          type: string
          description: The private key for the AKP kty.
        seed:
          type: string
          description: Seed used to derive keys for ML-DSA alg.
        e:
          type: string
          description: The exponent for the RSA public key.
        n:
          type: string
          description: The modulus for the RSA public key.
        d:
          type: string
          description: The private exponent for the RSA kty.
        p:
          type: string
          description: The first prime factor for the RSA private key.
        q:
          type: string
          description: The second prime factor for the RSA private key.
        dp:
          type: string
          description: The first factor CRT exponent for the RSA private key.
        dq:
          type: string
          description: The second factor CRT exponent for the RSA private key.
        qi:
          type: string
          description: The first CRT coefficient for the RSA private key.
      description: "JWK represents:\n - a JSON Web Key (JWK) with the respective fields specific to RSA algorithms.\n - a Quantum JSON Web Key (QJWK) with the respective fields specific to AKP algorithms."
    Issuer:
      type: object
      properties:
        organization:
          type: string
          description: The organization of the issuer
        subOrganization:
          type: string
          description: The sub organization of the issuer
        commonName:
          type: string
          description: "The common name of the issuer\n Could be a FQDN or a FQDA"
        verified:
          type: boolean
          description: "This will be set to true when issuer provides a valid proof of ownership\n of the common name on registration"
        publicKey:
          allOf:
          - $ref: '#/components/schemas/Jwk'
          description: "This field is optional\n The keys of the issuer in JWK format\n The public key is used to verify the signature of the different claims"
        privateKey:
          allOf:
          - $ref: '#/components/schemas/Jwk'
          description: "This field is optional\n The private key of the issuer in JWK format"
        authType:
          enum:
          - ISSUER_AUTH_TYPE_UNSPECIFIED
          - ISSUER_AUTH_TYPE_IDP
          - ISSUER_AUTH_TYPE_SELF
          type: string
          description: "This field specifies the authentication mechanism used by the issuer.\n It determines whether the issuer uses an external Identity Provider (IDP)\n or a self-issued key for authentication."
          format: enum
      description: A Identity Issuer