openapi: "3.0.3"

info:
  title: SentryAgent.ai — W3C DID & AGNTCY Agent Card
  version: 1.0.0
  description: |
    W3C Decentralized Identifier (DID) and AGNTCY Agent Card endpoints for the
    SentryAgent.ai AgentIdP platform.

    **Unauthenticated endpoints:**
    - `GET /.well-known/did.json` — Instance-level DID Document for the IdP itself
    - `GET /api/v1/agents/:agentId/did` — Per-agent W3C DID Document
    - `GET /api/v1/agents/:agentId/did/card` — AGNTCY-format agent card

    **Authenticated endpoint** (requires Bearer JWT + OPA authorization):
    - `GET /api/v1/agents/:agentId/did/resolve` — W3C DID Resolution result

    All DID Documents conform to the **W3C DID Core 1.0** specification.
    Agent cards conform to the **AGNTCY** agent identity standard (Linux Foundation).

servers:
  - url: http://localhost:3000
    description: Local development server
  - url: https://api.sentryagent.ai
    description: Production server

tags:
  - name: DID Documents
    description: W3C DID Document endpoints (unauthenticated)
  - name: DID Resolution
    description: Authenticated W3C DID Resolution endpoint
  - name: Agent Card
    description: AGNTCY agent card endpoint (unauthenticated)

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT access token obtained via `POST /api/v1/token`.
        Include as `Authorization: Bearer <token>`.

  schemas:
    PublicKeyJwk:
      type: object
      description: JWK representation of a public key embedded in a verification method.
      required:
        - kty
      properties:
        kty:
          type: string
          description: Key type (e.g. "EC", "RSA").
          example: "EC"
        crv:
          type: string
          description: EC curve (e.g. "P-256").
          example: "P-256"
        x:
          type: string
          description: Base64url-encoded EC x coordinate.
          example: "f83OJ3D..."
        y:
          type: string
          description: Base64url-encoded EC y coordinate.
          example: "x_FEzRu..."
        n:
          type: string
          description: Base64url-encoded RSA modulus.
        e:
          type: string
          description: Base64url-encoded RSA public exponent.
          example: "AQAB"
        use:
          type: string
          example: "sig"
        kid:
          type: string
          example: "key-20260328-001"

    VerificationMethod:
      type: object
      description: W3C DID Core 1.0 verification method.
      required:
        - id
        - type
        - controller
        - publicKeyJwk
      properties:
        id:
          type: string
          description: Full DID URL for this verification method.
          example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
        type:
          type: string
          description: Verification method type.
          example: "JsonWebKey2020"
        controller:
          type: string
          description: DID that controls this key.
          example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        publicKeyJwk:
          $ref: '#/components/schemas/PublicKeyJwk'

    DIDService:
      type: object
      description: A W3C DID Document service endpoint.
      required:
        - id
        - type
        - serviceEndpoint
      properties:
        id:
          type: string
          example: "did:web:api.sentryagent.ai:agents:a1b2c3d4#agentIdP"
        type:
          type: string
          example: "AgentIdP"
        serviceEndpoint:
          type: string
          format: uri
          example: "https://api.sentryagent.ai/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

    AgntcyExtension:
      type: object
      description: AGNTCY-specific extension fields embedded in a per-agent DID Document.
      required:
        - agentId
        - agentType
        - capabilities
        - deploymentEnv
        - owner
        - version
      properties:
        agentId:
          type: string
          format: uuid
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        agentType:
          type: string
          example: "screener"
        capabilities:
          type: array
          items:
            type: string
          example: ["resume:read", "email:send"]
        deploymentEnv:
          type: string
          example: "production"
        owner:
          type: string
          example: "talent-acquisition-team"
        version:
          type: string
          example: "1.4.2"

    DIDDocument:
      type: object
      description: W3C DID Core 1.0 DID Document.
      required:
        - "@context"
        - id
        - controller
        - verificationMethod
        - authentication
      properties:
        "@context":
          type: array
          items:
            type: string
          description: JSON-LD context URIs.
          example:
            - "https://www.w3.org/ns/did/v1"
            - "https://w3id.org/security/suites/jws-2020/v1"
        id:
          type: string
          description: The DID identifier for this document.
          example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        controller:
          type: string
          description: DID of the controlling entity.
          example: "did:web:api.sentryagent.ai"
        verificationMethod:
          type: array
          items:
            $ref: '#/components/schemas/VerificationMethod'
        authentication:
          type: array
          items:
            type: string
          description: DID URLs referencing verification methods authorized for authentication.
          example:
            - "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
        assertionMethod:
          type: array
          items:
            type: string
        service:
          type: array
          items:
            $ref: '#/components/schemas/DIDService'
        agntcy:
          $ref: '#/components/schemas/AgntcyExtension'

    DIDResolutionResult:
      type: object
      description: |
        W3C DID Resolution result format.
        Returned with `Content-Type: application/ld+json;profile="https://w3id.org/did-resolution"`.
      required:
        - didDocument
        - didDocumentMetadata
        - didResolutionMetadata
      properties:
        didDocument:
          $ref: '#/components/schemas/DIDDocument'
        didDocumentMetadata:
          type: object
          required:
            - created
            - updated
            - deactivated
          properties:
            created:
              type: string
              format: date-time
              example: "2026-03-01T08:00:00.000Z"
            updated:
              type: string
              format: date-time
              example: "2026-03-28T11:30:00.000Z"
            deactivated:
              type: boolean
              example: false
        didResolutionMetadata:
          type: object
          required:
            - contentType
            - retrieved
          properties:
            contentType:
              type: string
              example: "application/ld+json"
            retrieved:
              type: string
              format: date-time
              example: "2026-04-07T09:00:00.000Z"

    AgentCard:
      type: object
      description: |
        AGNTCY-format agent card providing a machine-readable identity summary.
        Suitable for AGNTCY registry publishing and agent discovery.
      required:
        - did
        - name
        - agentType
        - capabilities
        - owner
        - version
        - deploymentEnv
        - identityProvider
        - issuedAt
      properties:
        did:
          type: string
          description: W3C DID identifier for this agent.
          example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: Human-readable agent name (derived from email).
          example: "screener-001@sentryagent.ai"
        agentType:
          type: string
          example: "screener"
        capabilities:
          type: array
          items:
            type: string
          example: ["resume:read", "email:send", "candidate:score"]
        owner:
          type: string
          example: "talent-acquisition-team"
        version:
          type: string
          example: "1.4.2"
        deploymentEnv:
          type: string
          example: "production"
        identityProvider:
          type: string
          format: uri
          description: URL of the issuing AgentIdP instance.
          example: "https://api.sentryagent.ai"
        issuedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when this card was generated.
          example: "2026-04-07T09:00:00.000Z"

    ErrorResponse:
      type: object
      description: Standard error response envelope.
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: "AGENT_NOT_FOUND"
        message:
          type: string
          example: "Agent with the specified ID was not found."
        details:
          type: object
          additionalProperties: true

  responses:
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "UNAUTHORIZED"
            message: "A valid Bearer token is required to access this resource."

    Forbidden:
      description: Valid token but insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "FORBIDDEN"
            message: "You do not have permission to perform this action."

    NotFound:
      description: Agent not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "AGENT_NOT_FOUND"
            message: "Agent with the specified ID was not found."

    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "INTERNAL_SERVER_ERROR"
            message: "An unexpected error occurred. Please try again later."

paths:
  /.well-known/did.json:
    get:
      operationId: getInstanceDIDDocument
      tags:
        - DID Documents
      summary: Instance-level DID Document
      description: |
        Returns the W3C DID Document for the SentryAgent.ai AgentIdP instance itself.
        This identifies the IdP as a DID controller (`did:web:api.sentryagent.ai`).

        Used by external parties to discover the IdP's public keys and service endpoints.
        This endpoint is **unauthenticated**.
      security: []
      responses:
        '200':
          description: Instance DID Document returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DIDDocument'
              example:
                "@context":
                  - "https://www.w3.org/ns/did/v1"
                  - "https://w3id.org/security/suites/jws-2020/v1"
                id: "did:web:api.sentryagent.ai"
                controller: "did:web:api.sentryagent.ai"
                verificationMethod:
                  - id: "did:web:api.sentryagent.ai#key-1"
                    type: "JsonWebKey2020"
                    controller: "did:web:api.sentryagent.ai"
                    publicKeyJwk:
                      kty: "EC"
                      crv: "P-256"
                      x: "f83OJ3D..."
                      y: "x_FEzRu..."
                authentication:
                  - "did:web:api.sentryagent.ai#key-1"
                service:
                  - id: "did:web:api.sentryagent.ai#agentIdP"
                    type: "AgentIdP"
                    serviceEndpoint: "https://api.sentryagent.ai/api/v1"
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/v1/agents/{agentId}/did:
    get:
      operationId: getAgentDIDDocument
      tags:
        - DID Documents
      summary: Get agent DID Document
      description: |
        Returns the W3C DID Core 1.0 Document for a specific registered agent.

        Returns `410 Gone` if the agent has been decommissioned — the DID Document
        is no longer active.

        This endpoint is **unauthenticated**.
      security: []
      parameters:
        - name: agentId
          in: path
          required: true
          description: UUID of the agent.
          schema:
            type: string
            format: uuid
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        '200':
          description: Agent DID Document returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DIDDocument'
              example:
                "@context":
                  - "https://www.w3.org/ns/did/v1"
                  - "https://w3id.org/security/suites/jws-2020/v1"
                id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                controller: "did:web:api.sentryagent.ai"
                verificationMethod:
                  - id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
                    type: "JsonWebKey2020"
                    controller: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    publicKeyJwk:
                      kty: "EC"
                      crv: "P-256"
                      x: "f83OJ3D..."
                      y: "x_FEzRu..."
                authentication:
                  - "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
                agntcy:
                  agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                  agentType: "screener"
                  capabilities:
                    - "resume:read"
                    - "email:send"
                  deploymentEnv: "production"
                  owner: "talent-acquisition-team"
                  version: "1.4.2"
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          description: Agent has been decommissioned — DID Document is no longer active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: "AGENT_DECOMMISSIONED"
                message: "Agent has been decommissioned — DID Document is no longer active"
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/v1/agents/{agentId}/did/resolve:
    get:
      operationId: resolveAgentDID
      tags:
        - DID Resolution
      summary: Resolve agent DID (W3C DID Resolution)
      description: |
        Returns the full W3C DID Resolution result for a specific agent, including
        the DID Document, DID Document Metadata, and DID Resolution Metadata.

        The response `Content-Type` is:
        `application/ld+json;profile="https://w3id.org/did-resolution"`

        Requires a valid Bearer JWT and OPA authorization.
      security:
        - BearerAuth: []
      parameters:
        - name: agentId
          in: path
          required: true
          description: UUID of the agent to resolve.
          schema:
            type: string
            format: uuid
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        '200':
          description: DID Resolution result returned successfully.
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/DIDResolutionResult'
              example:
                didDocument:
                  "@context":
                    - "https://www.w3.org/ns/did/v1"
                  id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                  controller: "did:web:api.sentryagent.ai"
                  verificationMethod: []
                  authentication: []
                didDocumentMetadata:
                  created: "2026-03-01T08:00:00.000Z"
                  updated: "2026-03-28T11:30:00.000Z"
                  deactivated: false
                didResolutionMetadata:
                  contentType: "application/ld+json"
                  retrieved: "2026-04-07T09:00:00.000Z"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /api/v1/agents/{agentId}/did/card:
    get:
      operationId: getAgentCard
      tags:
        - Agent Card
      summary: Get AGNTCY agent card
      description: |
        Returns the AGNTCY-format agent card for the specified agent.
        The card provides a machine-readable identity summary suitable for
        AGNTCY registry publishing and agent discovery by external consumers.

        This endpoint is **unauthenticated**.
      security: []
      parameters:
        - name: agentId
          in: path
          required: true
          description: UUID of the agent.
          schema:
            type: string
            format: uuid
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      responses:
        '200':
          description: AGNTCY agent card returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCard'
              example:
                did: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "screener-001@sentryagent.ai"
                agentType: "screener"
                capabilities:
                  - "resume:read"
                  - "email:send"
                  - "candidate:score"
                owner: "talent-acquisition-team"
                version: "1.4.2"
                deploymentEnv: "production"
                identityProvider: "https://api.sentryagent.ai"
                issuedAt: "2026-04-07T09:00:00.000Z"
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'