AGNTCY ID Service API

openapi: 3.2.0
info:
  title: Identity Node ID 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: IdService
  description: IdService is the service that provides ID operations.
paths:
  /v1alpha1/id/generate:
    post:
      tags:
      - IdService
      description: Generate an Id and its corresponding ResolverMetadata for the specified Issuer
      operationId: IdService_Generate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1alpha1/id/resolve:
    post:
      tags:
      - IdService
      description: Resolve a specified Id to its corresponding ResolverMetadata
      operationId: IdService_Resolve
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveResponse'
        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."
    VerificationMethod:
      type: object
      properties:
        id:
          type: string
          description: A unique id of the verification method.
        publicKeyJwk:
          allOf:
          - $ref: '#/components/schemas/Jwk'
          description: The public key used for the verification method.
      description: "VerificationMethod expresses verification methods, such as cryptographic\n public keys, which can be used to authenticate or authorize interactions\n with the entities represented by the ID. It is a part of the ResolverMetadata."
    ResolveRequest:
      type: object
      properties:
        id:
          type: string
          description: Id is the identifier.
      description: Resolve a specified Id to its corresponding ResolverMetadata
    Service:
      type: object
      properties:
        serviceEndpoint:
          type: array
          items:
            type: string
          description: "ServiceEndpoint is a network address, such as an HTTP URL, of the\n node."
      description: "Service is used in ResolverMetadata to express ways of communicating with\n the node that published the document."
    GenerateResponse:
      type: object
      properties:
        resolverMetadata:
          allOf:
          - $ref: '#/components/schemas/ResolverMetadata'
          description: The ResolverMetadata corresponding to the generated Id
      description: Returns the Generated Id and its corresponding ResolverMetadata
    ResolveResponse:
      type: object
      properties:
        resolverMetadata:
          allOf:
          - $ref: '#/components/schemas/ResolverMetadata'
          description: The ResolverMetadata resolved from the Id
      description: Returns the ResolverMetadata corresponding to the specified Id
    ResolverMetadata:
      type: object
      properties:
        id:
          type: string
          description: "The ID\n The metadata below is related as claims to the ID"
        verificationMethod:
          type: array
          items:
            $ref: '#/components/schemas/VerificationMethod'
          description: "VerificationMethod is a list of cryptographic public keys, which can be used\n to authenticate or authorize interactions with the entities represented by the ID."
        service:
          type: array
          items:
            $ref: '#/components/schemas/Service'
          description: "Service is used in ResolverMetadatas to express ways of communicating with\n the node that published the document."
        assertionMethod:
          type: array
          items:
            type: string
          description: "AssertionMethod is used to specify how the entity represented by the ID\n is expected to express claims, such as for the purposes of issuing a VCs."
        controller:
          type: string
          description: A controller is an entity that is authorized to make changes to a Resolver Metadata.
      description: "ResolverMetadata represents a set of data describing the ID including mechanisms such as:\n   - cryptographic public keys - used to authenticate itself and prove\n     association with the ID\n   - service - ways of communicating with the node that published the document\n\n A ResolverMetadata can be retrieved by resolving an ID."
    GenerateRequest:
      type: object
      properties:
        issuer:
          allOf:
          - $ref: '#/components/schemas/Issuer'
          description: The Issuer details
        proof:
          allOf:
          - $ref: '#/components/schemas/Proof'
          description: "Optional Proof of ownership of the Issuer's provided id\n This should be provided when the Issuer is provided by an external IdP\n Example: a signed JWT"
      description: "Generate an Id and its corresponding ResolverMetadata for the specified Issuer\n For external IdPs, the Issuer should be provided with a Proof of ownership\n of the Issuer's provided id"
    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).'
    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