> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Redeem installation credential

> The registered app backend authenticates with a signed client assertion and a single-use code. Plaintext is returned only once; retries return status and never create another credential.



## OpenAPI

````yaml https://api.photon.codes/openapi.json post /v1/installation-requests/redeem
openapi: 3.1.0
info:
  title: Photon API
  version: 1.0.0
servers:
  - url: https://api.photon.codes
security: []
paths:
  /v1/installation-requests/redeem:
    post:
      tags:
        - App Installations
      summary: Redeem installation credential
      description: >-
        The registered app backend authenticates with a signed client assertion
        and a single-use code. Plaintext is returned only once; retries return
        status and never create another credential.
      operationId: redeemAppInstallationDelivery
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemAppInstallationDeliveryRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemAppInstallationDeliveryResponse'
          description: First successful delivery or metadata-only operation status.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InvalidArgumentProblem'
          description: 'INVALID_ARGUMENT: Invalid Argument'
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/AppInstallationAssertionInvalidProblem'
          description: >-
            APP_INSTALLATION_ASSERTION_INVALID: Invalid Installation Client
            Assertion
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/AppInstallationDeliveryUnavailableProblem'
          description: >-
            APP_INSTALLATION_DELIVERY_UNAVAILABLE: Installation Delivery
            Unavailable
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationFailedProblem'
          description: 'VALIDATION_FAILED: Request Validation Failed'
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UpstreamFailureProblem'
          description: 'UPSTREAM_FAILURE: Upstream Service Failure'
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UpstreamUnavailableProblem'
          description: 'UPSTREAM_UNAVAILABLE: Upstream Service Unavailable'
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
        '504':
          content:
            application/problem+json:
              schema:
                $ref: >-
                  #/components/schemas/RedeemAppInstallationDeliveryGatewayTimeoutProblem
          description: >-
            UPSTREAM_TIMEOUT: Upstream Service Timeout; REQUEST_TIMEOUT: Request
            Timeout
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
            Link:
              $ref: '#/components/headers/Link'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Trace-ID:
              $ref: '#/components/headers/X-Trace-ID'
      security: []
components:
  schemas:
    RedeemAppInstallationDeliveryRequest:
      additionalProperties: false
      properties:
        appId:
          pattern: ^pho_app_[0-7][0-9a-hjkmnp-tv-z]{25}$
          type: string
        clientAssertion:
          maxLength: 16384
          minLength: 1
          type: string
        code:
          pattern: ^[A-Za-z0-9_-]{43}$
          type: string
      required:
        - appId
        - clientAssertion
        - code
      type: object
    RedeemAppInstallationDeliveryResponse:
      oneOf:
        - $ref: '#/components/schemas/CreatedAppInstallationDelivery'
        - $ref: '#/components/schemas/ExistingAppInstallationDelivery'
    InvalidArgumentProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: INVALID_ARGUMENT
        status: 400
        title: Invalid Argument
        type: https://photon.codes/docs/problems/invalid-argument
      properties:
        code:
          const: INVALID_ARGUMENT
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 400
          type: number
        title:
          const: Invalid Argument
          type: string
        type:
          const: https://photon.codes/docs/problems/invalid-argument
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    AppInstallationAssertionInvalidProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: APP_INSTALLATION_ASSERTION_INVALID
        status: 401
        title: Invalid Installation Client Assertion
        type: https://photon.codes/docs/problems/app-installation-assertion-invalid
      properties:
        code:
          const: APP_INSTALLATION_ASSERTION_INVALID
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 401
          type: number
        title:
          const: Invalid Installation Client Assertion
          type: string
        type:
          const: >-
            https://photon.codes/docs/problems/app-installation-assertion-invalid
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    AppInstallationDeliveryUnavailableProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: APP_INSTALLATION_DELIVERY_UNAVAILABLE
        status: 409
        title: Installation Delivery Unavailable
        type: >-
          https://photon.codes/docs/problems/app-installation-delivery-unavailable
      properties:
        code:
          const: APP_INSTALLATION_DELIVERY_UNAVAILABLE
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 409
          type: number
        title:
          const: Installation Delivery Unavailable
          type: string
        type:
          const: >-
            https://photon.codes/docs/problems/app-installation-delivery-unavailable
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    ValidationFailedProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: VALIDATION_FAILED
        issues:
          - code: invalid_type
            location: json
            message: Expected a string.
            path: /name
        status: 422
        title: Request Validation Failed
        type: https://photon.codes/docs/problems/validation-failed
      properties:
        code:
          const: VALIDATION_FAILED
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        issues:
          items:
            $ref: '#/components/schemas/ValidationIssue'
          type: array
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 422
          type: number
        title:
          const: Request Validation Failed
          type: string
        type:
          const: https://photon.codes/docs/problems/validation-failed
          type: string
      required:
        - issues
        - code
        - status
        - title
        - type
      type: object
    UpstreamFailureProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: UPSTREAM_FAILURE
        status: 502
        title: Upstream Service Failure
        type: https://photon.codes/docs/problems/upstream-failure
      properties:
        code:
          const: UPSTREAM_FAILURE
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 502
          type: number
        title:
          const: Upstream Service Failure
          type: string
        type:
          const: https://photon.codes/docs/problems/upstream-failure
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    UpstreamUnavailableProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: UPSTREAM_UNAVAILABLE
        status: 503
        title: Upstream Service Unavailable
        type: https://photon.codes/docs/problems/upstream-unavailable
      properties:
        code:
          const: UPSTREAM_UNAVAILABLE
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 503
          type: number
        title:
          const: Upstream Service Unavailable
          type: string
        type:
          const: https://photon.codes/docs/problems/upstream-unavailable
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    RedeemAppInstallationDeliveryGatewayTimeoutProblem:
      oneOf:
        - $ref: '#/components/schemas/UpstreamTimeoutProblem'
        - $ref: '#/components/schemas/RequestTimeoutProblem'
    CreatedAppInstallationDelivery:
      additionalProperties: false
      properties:
        clientId:
          maxLength: 256
          pattern: ^client_[A-Za-z0-9]+$
          type: string
        clientSecret:
          maxLength: 8192
          minLength: 1
          type: string
        installationId:
          pattern: ^pho_ain_[0-7][0-9a-hjkmnp-tv-z]{25}$
          type: string
        status:
          const: created
          type: string
      required:
        - installationId
        - status
        - clientId
        - clientSecret
      type: object
    ExistingAppInstallationDelivery:
      additionalProperties: false
      properties:
        installationId:
          pattern: ^pho_ain_[0-7][0-9a-hjkmnp-tv-z]{25}$
          type: string
        status:
          $ref: '#/components/schemas/ExistingAppInstallationDeliveryStatus'
      required:
        - installationId
        - status
      type: object
    JsonValue:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - items:
            $ref: '#/components/schemas/JsonValue'
          type: array
        - additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          propertyNames:
            type: string
          type: object
    ValidationIssue:
      additionalProperties: false
      properties:
        code:
          minLength: 1
          type: string
        location:
          $ref: '#/components/schemas/ValidationLocation'
        message:
          minLength: 1
          type: string
        path:
          type: string
      required:
        - code
        - location
        - message
        - path
      type: object
    UpstreamTimeoutProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: UPSTREAM_TIMEOUT
        status: 504
        title: Upstream Service Timeout
        type: https://photon.codes/docs/problems/upstream-timeout
      properties:
        code:
          const: UPSTREAM_TIMEOUT
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 504
          type: number
        title:
          const: Upstream Service Timeout
          type: string
        type:
          const: https://photon.codes/docs/problems/upstream-timeout
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    RequestTimeoutProblem:
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
      example:
        code: REQUEST_TIMEOUT
        status: 504
        title: Request Timeout
        type: https://photon.codes/docs/problems/request-timeout
      properties:
        code:
          const: REQUEST_TIMEOUT
          type: string
        detail:
          minLength: 1
          type: string
        instance:
          minLength: 1
          type: string
        remediation:
          not: {}
        requestId:
          minLength: 1
          type: string
        status:
          const: 504
          type: number
        title:
          const: Request Timeout
          type: string
        type:
          const: https://photon.codes/docs/problems/request-timeout
          type: string
      required:
        - code
        - status
        - title
        - type
      type: object
    ExistingAppInstallationDeliveryStatus:
      enum:
        - delivery_consumed
        - recovery_required
        - revocation_pending
        - revoked
      type: string
    ValidationLocation:
      enum:
        - body
        - cookie
        - form
        - header
        - json
        - param
        - query
      type: string
  headers:
    Deprecation:
      description: >-
        RFC 9745 structured-field Date at which the operation was or will be
        deprecated: `@` followed by Unix seconds, for example `@1767225599`.
      schema:
        pattern: ^@-?[0-9]+$
        type: string
    Idempotent-Replayed:
      description: True when this response was replayed from an earlier attempt.
      schema:
        type: boolean
    Link:
      description: Links related to lifecycle or remediation documentation.
      schema:
        type: string
    RateLimit:
      description: Current rate-limit state.
      schema:
        type: string
    RateLimit-Policy:
      description: Rate-limit policy applied by the gateway.
      schema:
        type: string
    Retry-After:
      description: Delay before retrying, in seconds or as an HTTP date.
      schema:
        type: string
    Sunset:
      description: >-
        RFC 8594 HTTP-date (IMF-fixdate) after which the operation may become
        unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`.
      schema:
        pattern: >-
          ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2}
          (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4}
          [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$
        type: string
    X-Request-ID:
      description: Identifier for this HTTP attempt.
      schema:
        type: string
    X-Trace-ID:
      description: >-
        Trace ID of this request. Sent alongside X-Request-ID when a middleware
        published a trace ID for the request.
      schema:
        pattern: ^(?!0{32}$)[0-9a-f]{32}$
        type: string

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.