auth-server-open-api-spec.yaml

openapi: 3.1.0
info:
  title: Open Payments Authorization Server
  version: '1.0'
  license:
    name: Apache 2.0
    identifier: Apache-2.0
  summary: Open Payments GNAP Authorization Server
  description: 'The Open Payments API is secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the Open Payments Authorization Server API, which is an opiniated GNAP Server API.'
  contact:
    email: tech@interledger.org
servers:
  - url: 'https://openpayments.guide/auth'
tags:
  - name: grant
    description: grant operations
  - name: token
    description: token operations
  - name: interaction
    description: User interaction endpoints
paths:
  /:
    post:
      summary: Grant Request
      operationId: post
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  interact:
                    $ref: '#/components/schemas/interact-response'
                  continue:
                    $ref: '#/components/schemas/continue'
                required:
                  - interact
                  - continue
              examples:
                Interaction instructions:
                  value:
                    interact:
                      redirect: 'https://openpayments.guide/auth/4CF492MLVMSW9MKMXKHQ'
                      finish: 4105340a-05eb-4290-8739-f9e2b463bfa7
                    continue:
                      access_token:
                        value: 33OMUKMKSKU80UPRY5NM
                      uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ'
                      wait: 30
        '400':
          description: Bad Request
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                access_token:
                  type: object
                  required:
                    - access
                  properties:
                    access:
                      type: array
                      description: Describes the rights that the client instance is requesting for one or more access tokens to be used at RS's.
                      items:
                        $ref: '#/components/schemas/access'
                client:
                  $ref: '#/components/schemas/client'
                interact:
                  $ref: '#/components/schemas/interact-request'
              required:
                - access_token
                - client
                - interact
            examples:
              Grant for recurring fixed payment:
                value:
                  access_token:
                    access:
                      - type: outgoing-payment
                        actions:
                          - create
                          - read
                        identifier: 'https://openpayments.guide/alice'
                        interval: 'R12/2019-08-24T14:15:22Z/P1M'
                        limits:
                          receiver: 'https://openpayments.guide/connections/45a0d0ee-26dc-4c66-89e0-01fbf93156f7'
                          sendAmount:
                            value: '500'
                            assetCode: USD
                            assetScale: 2
                  client:
                    display:
                      name: Webmonize
                      uri: 'https://webmonize.com'
                    key:
                      proof: httpsig
                      jwk:
                        alg: EdDSA
                        kid: 20f24ce2-a5f6-4f28-bf7d-ed52d0490187
                        kty: OKP
                        use: sig
                        crv: Ed25519
                        x: AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q
                  interact:
                    start:
                      - redirect
                    finish:
                      method: redirect
                      uri: 'https://webmonize.com/return/876FGRD8VC'
                      nonce: 4edb2194-dbdf-46bb-9397-d5fd57b7c8a7
        description: ''
      description: Make a new grant request
      security: []
      tags:
        - grant
    parameters: []
  '/continue/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    post:
      summary: Continuation Request
      operationId: post-continue
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    $ref: '#/components/schemas/access_token'
                  continue:
                    $ref: '#/components/schemas/continue'
              examples:
                Continuing After a Completed Interaction:
                  value:
                    access_token:
                      value: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
                      manage: 'https://openpayments.guide/auth/token/dd17a202-9982-4ed9-ae31-564947fb6379'
                      expires_in: 3600
                      access:
                        - type: outgoing-payment
                          actions:
                            - create
                            - read
                          identifier: 'https://openpayments.guide/alice'
                          interval: 'R12/2019-08-24T14:15:22Z/P1M'
                          limits:
                            receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2'
                            sendAmount:
                              value: '500'
                              assetCode: USD
                              assetScale: 2
                    continue:
                      access_token:
                        value: 33OMUKMKSKU80UPRY5NM
                      uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ'
                      wait: 30
                Continuing During Pending Interaction:
                  value:
                    continue:
                      access_token:
                        value: 33OMUKMKSKU80UPRY5NM
                      uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ'
                      wait: 30
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                interact_ref:
                  type: string
                  description: |-
                    The interaction reference generated for this
                    interaction by the AS.
              required:
                - interact_ref
            examples:
              Interaction Reference:
                value:
                  interact_ref: ad82597c-bbfa-4eb0-b72e-328e005b8689
      description: Continue a grant request during or after user interaction.
      tags:
        - grant
    patch:
      summary: Update Request
      operationId: patch-continue
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    $ref: '#/components/schemas/access_token'
                  continue:
                    $ref: '#/components/schemas/continue'
                required:
                  - access_token
                  - continue
              examples:
                Add list access:
                  value:
                    access_token:
                      value: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
                      manage: 'https://openpayments.guide/auth/token'
                      expires_in: 3600
                      access:
                        - type: outgoing-payment
                          actions:
                            - create
                            - read
                          identifier: 'https://openpayments.guide/alice'
                          interval: 'R12/2019-08-24T14:15:22Z/P1M'
                          limits:
                            receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2'
                            sendAmount:
                              value: '500'
                              assetCode: USD
                              assetScale: 2
                        - type: outgoing-payment
                          actions:
                            - list
                          identifier: 'https://openpayments.guide/alice'
                    continue:
                      access_token:
                        value: 33OMUKMKSKU80UPRY5NM
                      uri: 'https://openpayments.guide/auth/continue/4CF492MLVMSW9MKMXKHQ'
                      wait: 30
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      description: Modify an existing grant request.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  required:
                    - access
                  type: object
                  properties:
                    access:
                      type: array
                      description: Describes the rights that the client instance is requesting for one or more access tokens to be used at RS's.
                      items:
                        $ref: '#/components/schemas/access'
              required:
                - access_token
            examples:
              Add list access:
                value:
                  access_token:
                    access:
                      - type: outgoing-payment
                        actions:
                          - create
                          - read
                        identifier: 'https://openpayments.guide/alice'
                        interval: 'R12/2019-08-24T14:15:22Z/P1M'
                        limits:
                          receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2'
                          sendAmount:
                            value: '500'
                            assetCode: USD
                            assetScale: 2
                      - type: outgoing-payment
                        actions:
                          - list
                        identifier: 'https://openpayments.guide/alice'
      tags:
        - grant
    delete:
      summary: Cancel Grant Request
      operationId: delete-continue
      responses:
        '202':
          description: Accepted
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      description: Cancel a grant request.
      tags:
        - grant
  '/token/{id}':
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    post:
      summary: Rotate Access Token
      operationId: post-token
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    $ref: '#/components/schemas/access_token'
                required:
                  - access_token
              examples:
                New access token:
                  value:
                    access_token:
                      value: OZB8CDFONP219RP1LT0OS9M2PMHKUR64TB8N6BW7
                      manage: 'https://openpayments.guide/auth/token/8f69de01-5bf9-4603-91ed-eeca101081f1'
                      expires_in: 3600
                      access:
                        - type: outgoing-payment
                          actions:
                            - create
                            - read
                          identifier: 'https://openpayments.guide/alice'
                          interval: 'R12/2019-08-24T14:15:22Z/P1M'
                          limits:
                            receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2'
                            sendAmount:
                              value: '500'
                              assetCode: USD
                              assetScale: 2
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      description: Management endpoint to rotate access token.
      tags:
        - token
    delete:
      summary: Revoke Access Token
      operationId: delete-token
      description: Management endpoint to revoke access token.
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
      tags:
        - token
  /introspect:
    parameters: []
    post:
      summary: Introspect Access Token
      operationId: post-introspect
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  active:
                    type: boolean
                  grant:
                    type: string
                  access:
                    type: array
                    items:
                      $ref: '#/components/schemas/access'
                  key:
                    $ref: '#/components/schemas/key'
                required:
                  - active
              examples:
                Token Introspection:
                  value:
                    active: true
                    grant: 1ee48d97-8fa1-4ab4-b89d-95284b665517
                    access:
                      - type: outgoing-payment
                        actions:
                          - create
                          - read
                        identifier: 'https://openpayments.guide/alice'
                        interval: 'R12/2019-08-24T14:15:22Z/P1M'
                        limits:
                          receiver: 'https://openpayments.guide/bob/incoming-payments/48884225-b393-4872-90de-1b737e2491c2'
                          sendAmount:
                            value: '500'
                            assetCode: USD
                            assetScale: 2
                    key:
                      proof: httpsig
                      jwk:
                        alg: EdDSA
                        kid: 20f24ce2-a5f6-4f28-bf7d-ed52d0490187
                        kty: OKP
                        use: sig
                        crv: Ed25519
                        x: AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q
        '404':
          description: Not Found
      description: Introspect an access token to get grant details.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  description: The access token value presented to the RS by the client instance.
                proof:
                  type: string
                  description: The proofing method used by the client instance to bind the token to the RS request.
                resource_server:
                  oneOf:
                    - $ref: '#/components/schemas/key'
                    - type: string
                  description: 'The identification used to authenticate the resource server making this call, either by value or by reference.'
                access:
                  type: array
                  description: The minimum access rights required to fulfill the request.
                  items:
                    $ref: '#/components/schemas/access'
              required:
                - access_token
                - resource_server
            examples:
              Introspect token:
                value:
                  access_token: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
                  proof: httpsig
                  resource_server: 7C7C4AZ9KHRS6X63AJAO
      tags:
        - token
  '/interact/{id}':
    get:
      summary: Start user interaction
      tags:
        - interaction
        - grant
      responses:
        '302':
          description: Found
          headers:
            Location:
              schema:
                type: string
              description: Identity server endpoint
            Cookie:
              schema:
                type: string
              description: Interaction id
      operationId: get-interact
      parameters: []
      description: 'To start the user interaction for grant approval, this endpoint redirects to identity server for authentication of the user.'
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Interaction id
    post:
      summary: Finish user interaction
      operationId: post-interact-id
      responses:
        '302':
          description: Found
          headers:
            Location:
              schema:
                type: string
              description: Client finish endpoint
      description: 'To finish the user interaction for grant approval, this endpoint redirects to the client''s finish url.'
      tags:
        - interaction
        - grant
      parameters:
        - schema:
            type: string
          in: cookie
          name: interactId
          description: Interaction id
components:
  schemas:
    access:
      discriminator:
        propertyName: type
        mapping:
          account: '#/components/schemas/access-account'
          incoming-payment: '#/components/schemas/access-incoming'
          outgoing-payment: '#/components/schemas/access-outgoing'
      oneOf:
        - $ref: '#/components/schemas/access-account'
        - $ref: '#/components/schemas/access-incoming'
        - $ref: '#/components/schemas/access-outgoing'
      description: The access associated with the access token is described using objects that each contain multiple dimensions of access.
    limits-outgoing:
      title: limits-outgoing
      description: Open Payments specific property that defines the limits under which outgoing payments can be created.
      type: object
      properties:
        receiver:
          type: string
          format: uri
          description: URL for the incoming payment or ILP STREAM Connection.
        sendAmount:
          $ref: '#/components/schemas/amount'
        receiveAmount:
          $ref: '#/components/schemas/amount'
        description:
          type: string
          description: Outgoing payments MUST be created using this description.
        externalRef:
          type: string
          description: Outgoing payments MUST be created using this external reference.
    amount:
      title: amount
      type: object
      description: 'All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.'
      properties:
        value:
          type: string
          format: uint64
          description: 'The value is an unsigned 64-bit integer amount, represented as a string.'
        assetCode:
          type: string
          description: The assetCode is a code that indicates the underlying asset. In most cases this SHOULD be a 3-character ISO 4217 currency code.
        assetScale:
          type: integer
          minimum: 0
          maximum: 255
          description: 'The assetScale indicates how the value has been scaled relative to the natural scale of the asset. For example, an value of "1234" with an assetScale of 2 represents an amount of 12.34.'
      required:
        - value
        - assetCode
        - assetScale
    client:
      title: client
      type: object
      properties:
        display:
          type: object
          description: 'An object containing additional information that the AS MAY display to the RO during interaction, authorization, and management.'
          properties:
            name:
              type: string
            uri:
              type: string
              format: uri
        client_id:
          type: string
          description: An identifier string that the AS can use to identify the client software comprising this client instance.
        key:
          oneOf:
            - $ref: '#/components/schemas/key'
            - type: string
          description: The public key of the client instance to be used in this request or a reference to a key.
      description: |-
        Describes the client instance that is making this request, including the key that the client instance will use to protect this request and any continuation requests at the AS and any user-facing information about the client instance used in interactions.
              
        When sending a non-continuation request to the AS, the client instance MUST identify itself by including the client field of the request and by signing the request.
    key:
      title: key
      type: object
      properties:
        proof:
          type: string
          enum:
            - httpsig
          description: The form of proof that the client instance will use when presenting the key.
        jwk:
          type: object
          description: 'The public key and its properties represented as a JSON Web Key [[RFC7517](https://datatracker.ietf.org/doc/html/rfc7517)].'
          required:
            - alg
            - kty
            - crv
            - x
          properties:
            alg:
              type: string
              description: 'The cryptographic algorithm family used with the key. The only allowed value is `EdDSA`. '
              enum:
                - EdDSA
            kid:
              type: string
              description: A Key ID can be used to match a specific key.
            kty:
              type: string
              enum:
                - OKP
              description: 'The Key Type. The only allowed value is `OKP`. '
            use:
              type: string
              enum:
                - sig
              description: The intended use of the key.
            crv:
              type: string
              enum:
                - Ed25519
              description: 'The cryptographic curve used with the key. The only allowed value is `Ed25519`. '
            x:
              type: string
              description: Public key encoded using the `base64url` encoding.
      required:
        - proof
        - jwk
      description: A key presented by value MUST be a public key.
    interact-request:
      title: interact
      type: object
      properties:
        start:
          type: array
          description: Indicates how the client instance can start an interaction.
          items:
            type: string
            enum:
              - redirect
        finish:
          type: object
          description: Indicates how the client instance can receive an indication that interaction has finished at the AS.
          properties:
            method:
              type: string
              enum:
                - redirect
              description: The callback method that the AS will use to contact the client instance.
            uri:
              type: string
              format: uri
              description: Indicates the URI that the AS will either send the RO to after interaction or send an HTTP POST request.
            nonce:
              type: string
              description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker.  MUST be generated by the client instance as a unique value for this request.'
          required:
            - method
            - uri
            - nonce
      required:
        - start
      description: The client instance declares the parameters for interaction methods that it can support using the interact field.
    interact-response:
      title: interact-response
      type: object
      properties:
        redirect:
          type: string
          format: uri
          description: The URI to direct the end user to.
        finish:
          type: string
          description: Unique key to secure the callback.
      required:
        - redirect
        - finish
    continue:
      title: continue
      type: object
      description: 'If the AS determines that the request can be continued with additional requests, it responds with the continue field.'
      properties:
        access_token:
          type: object
          description: 'A unique access token for continuing the request, called the "continuation access token".'
          required:
            - value
          properties:
            value:
              type: string
        uri:
          type: string
          format: uri
          description: The URI at which the client instance can make continuation requests.
        wait:
          type: integer
          description: The amount of time in integer seconds the client instance MUST wait after receiving this request continuation response and calling the continuation URI.
      required:
        - access_token
        - uri
    access_token:
      title: access_token
      type: object
      description: A single access token or set of access tokens that the client instance can use to call the RS on behalf of the RO.
      properties:
        value:
          type: string
          description: The value of the access token as a string.  The value is opaque to the client instance.  The value SHOULD be limited to ASCII characters to facilitate transmission over HTTP headers within other protocols without requiring additional encoding.
        manage:
          type: string
          format: uri
          description: The management URI for this access token. This URI MUST NOT include the access token value and SHOULD be different for each access token issued in a request.
        expires_in:
          type: integer
          description: The number of seconds in which the access will expire.  The client instance MUST NOT use the access token past this time.  An RS MUST NOT accept an access token past this time.
        access:
          type: array
          description: A description of the rights associated with this access token.
          items:
            $ref: '#/components/schemas/access'
      required:
        - value
        - manage
        - access
    access-outgoing:
      title: access-outgoing
      type: object
      properties:
        type:
          type: string
          enum:
            - outgoing-payment
          description: The type of resource request as a string.  This field defines which other fields are allowed in the request object.
        actions:
          type: array
          description: The types of actions the client instance will take at the RS as an array of strings.
          items:
            type: string
            enum:
              - create
              - read
              - read-all
              - list
              - list-all
        identifier:
          type: string
          format: uri
          description: A string identifier indicating a specific resource at the RS.
        limits:
          $ref: '#/components/schemas/limits-outgoing'
        interval:
          type: string
          description: '[ISO8601 repeating interval](https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals)'
      required:
        - type
        - actions
    access-incoming:
      title: access-incoming
      type: object
      properties:
        type:
          type: string
          enum:
            - incoming-payment
          description: The type of resource request as a string.  This field defines which other fields are allowed in the request object.
        actions:
          type: array
          description: The types of actions the client instance will take at the RS as an array of strings.
          items:
            type: string
            enum:
              - create
              - complete
              - read
              - read-all
              - list
              - list-all
        identifier:
          type: string
          format: uri
          description: A string identifier indicating a specific resource at the RS.
        limits:
          $ref: '#/components/schemas/limits-incoming'
        interval:
          type: string
          description: '[ISO8601 repeating interval](https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals)'
      required:
        - type
        - actions
    access-account:
      title: access-account
      type: object
      properties:
        type:
          type: string
          enum:
            - account
          description: The type of resource request as a string.  This field defines which other fields are allowed in the request object.
        actions:
          type: array
          description: The types of actions the client instance will take at the RS as an array of strings.
          items:
            type: string
            enum:
              - read
        identifier:
          type: string
          format: uri
          description: A string identifier indicating a specific resource at the RS.
        interval:
          type: string
          description: '[ISO8601 repeating interval](https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals)'
      required:
        - type
        - actions
    limits-incoming:
      title: limits-incoming
      type: object
      properties:
        incomingAmount:
          $ref: '#/components/schemas/amount'
        expiresAt:
          type: string
          format: date-time
          description: The date and time when the incoming payment will not accept any payments anymore.
        description:
          type: string
          description: Incoming payments MUST be created using this description.
        externalRef:
          type: string
          description: Incoming payments MUST be created using this external reference.
      description: 'Open Payments specific property that defines the limits under which incoming payments can be created. '
  securitySchemes:
    GNAP:
      name: Authorization
      type: apiKey
      in: header