OpenADR Alliance Auth API

openapi: 3.2.0
info:
  title: Openadr Alliance Auth API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: '1.0'
  description: 'Operations tagged Auth across 4 of this provider''s published API definitions: openadr-3-0-0-openapi.yaml, openadr-3-0-1-openapi.yaml, openadr-3-1-0-openapi.yaml, openadr-3-1-1-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- description: base path
  url: http://localhost:8081/openadr3
- description: base path
  url: http://localhost:8081/openadr3/3.0.1
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
tags:
- name: Auth
paths:
  /auth/token:
    get:
      parameters:
      - name: clientID
        in: header
        description: client ID to exchange for bearer token.
        required: true
        schema:
          type: string
          example: ven_client_99
      - name: clientSecret
        in: header
        description: client secret to exchange for bearer token.
        required: true
        schema:
          type: string
          example: ven_secret_99
      tags:
      - Auth
      summary: fetch a token
      operationId: fetchToken
      description: Return an access token based on clientID and clientSecret.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    post:
      tags:
      - Auth
      summary: fetch a token
      operationId: fetchToken
      description: Return an access token based on clientID and clientSecret.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/clientCredentialRequest'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clientCredentialResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authError'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    servers:
    - description: base path
      url: http://localhost:8081/openadr3
  /auth/server:
    get:
      tags:
      - Auth
      summary: fetch server info
      operationId: getAuthServerInfo
      description: Return the URL of the token endpoint.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authServerInfo'
        '500':
          $ref: '#/components/responses/internalServerError'
    servers:
    - description: SwaggerHub API Auto Mocking
      url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
components:
  schemas:
    problem:
      type: object
      description: 'reusable error response. From https://opensource.zalando.com/problem/schema.yaml.

        '
      properties:
        type:
          type: string
          format: uri
          description: 'An absolute URI that identifies the problem type.

            When dereferenced, it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).

            '
          default: about:blank
          example: https://zalando.github.io/problem/constraint-violation
        title:
          type: string
          description: 'A short, summary of the problem type. Written in english and readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable.

            '
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          example: 503
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Connection to database timed out
        instance:
          type: string
          format: uri
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
    authError:
      type: object
      description: error reponse on HTTP 400 from auth/token per https://www.rfc-editor.org/rfc/rfc6749
      required:
      - error
      properties:
        error:
          type: string
          description: As described in rfc6749 | invalid_request – The request is missing a parameter so the server can’t proceed with the request. This may also be returned if the request includes an unsupported parameter or repeats a parameter. invalid_client – Client authentication failed, such as if the request contains an invalid client ID or secret. Send an HTTP 401 response in this case. invalid_grant – The authorization code (or user’s password for the password grant type) is invalid or expired. This is also the error you would return if the redirect URL given in the authorization grant does not match the URL provided in this access token request. invalid_scope – For access token requests that include a scope (password or client_credentials grants), this error indicates an invalid scope value in the request. unauthorized_client – This client is not authorized to use the requested grant type. For example, if you restrict which applications can use the Implicit grant, you would return this error for the other apps. unsupported_grant_type – If a grant type is requested that the authorization server doesn’t recognize, use this code. Note that unknown grant types also use this specific error code rather than using the invalid_request above.
          example: invalid_request
          enum:
          - invalid_request
          - invalid_client
          - invalid_grant
          - invalid_scope
          - unauthorized_client
          - unsupported_grant_type
        error_description:
          type: string
          description: Should be a sentence or two at most describing the circumstance of the error
          example: Request was missing the 'client_id' parameter.
        error_uri:
          type: string
          format: uri
          description: Optional reference to more detailed error description
          example: See the full API docs at https://authorization-server.com/docs/access_toke
    clientCredentialResponse:
      type: object
      description: 'Body response from /auth/token. Note snake case per https://www.rfc-editor.org/rfc/rfc6749

        '
      required:
      - access_token
      - token_type
      properties:
        access_token:
          type: string
          minLength: 1
          maxLength: 4096
          description: access token povided by Authorization service
          example: MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3
        token_type:
          type: string
          description: token type, must be Bearer.
          example: Bearer
          enum:
          - Bearer
        expires_in:
          type: integer
          description: expiration period in seconds.
          example: 3600
        refresh_token:
          type: string
          minLength: 1
          maxLength: 4096
          description: refresh token povided by Authorization service
          example: IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk
        scope:
          type: string
          minLength: 0
          maxLength: 4096
          description: application defined scope.
          example: read_all
    clientCredentialRequest:
      type: object
      description: 'Body of POST request to /auth/token. Note snake case per https://www.rfc-editor.org/rfc/rfc6749

        '
      required:
      - grant_type
      - client_id
      - client_secret
      properties:
        grant_type:
          type: string
          description: OAuth2 grant type, must be 'client_credentials'
          example: client_credentials
          enum:
          - client_credentials
        client_id:
          type: string
          minLength: 1
          maxLength: 4096
          description: client ID to exchange for bearer token.
          example: ven_client_99
        client_secret:
          type: string
          minLength: 1
          maxLength: 4096
          description: client secret to exchange for bearer token.
          example: ven_secret_99
        scope:
          type: string
          minLength: 0
          maxLength: 4096
          description: application defined scope.
          example: read_all
    clientCredentialResponse_2:
      type: object
      description: 'Body response from /auth/token. Note snake case per https://www.rfc-editor.org/rfc/rfc6749

        '
      required:
      - access_token
      - token_type
      properties:
        access_token:
          type: string
          minLength: 1
          maxLength: 4096
          description: access token provided by Authorization service
          example: MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3
        token_type:
          type: string
          description: token type, must be Bearer.
          example: Bearer
          enum:
          - Bearer
        expires_in:
          type: integer
          description: expiration period in seconds.
          example: 3600
        refresh_token:
          type: string
          minLength: 1
          maxLength: 4096
          description: refresh token provided by Authorization service
          example: IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk
        scope:
          type: string
          minLength: 0
          maxLength: 4096
          description: application defined scope.
          example: read_all
    problem_2:
      type: object
      description: 'reusable error response. From https://opensource.zalando.com/problem/schema.yaml.

        '
      properties:
        type:
          type: string
          format: uri
          minLength: 2
          maxLength: 8000
          description: 'An absolute URI that identifies the problem type.

            When dereferenced, it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).

            '
          default: about:blank
          example: https://zalando.github.io/problem/constraint-violation
        title:
          type: string
          description: 'A short, summary of the problem type. Written in english and readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable.

            '
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          example: 503
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Connection to database timed out
        instance:
          type: string
          minLength: 3
          maxLength: 8000
          format: uri
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
    authServerInfo:
      type: object
      required:
      - tokenURL
      properties:
        tokenURL:
          type: string
          format: uri
          minLength: 2
          maxLength: 8000
          description: URL of the token endpoint.
    clientCredentialResponse_3:
      type: object
      description: 'Body response from /auth/token. Note snake case per https://www.rfc-editor.org/rfc/rfc6749

        '
      required:
      - access_token
      - token_type
      properties:
        access_token:
          type: string
          minLength: 1
          maxLength: 4096
          description: access token provided by Authorization service
          example: MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3
        token_type:
          type: string
          description: token type, must be Bearer.
          example: Bearer
          enum:
          - Bearer
        expires_in:
          type: integer
          description: expiration period in seconds.
          example: 3600
        refresh_token:
          type: string
          minLength: 1
          maxLength: 4096
          description: refresh token provided by Authorization service
          example: IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk
        scope:
          type: string
          minLength: 0
          maxLength: 4096
          description: application defined scope.
          example: read_all
    problem_3:
      type: object
      description: 'reusable error response. From https://opensource.zalando.com/problem/schema.yaml.

        '
      properties:
        type:
          type: string
          format: uri
          minLength: 2
          maxLength: 8000
          description: 'An absolute URI that identifies the problem type.

            When dereferenced, it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).

            '
          default: about:blank
          example: https://zalando.github.io/problem/constraint-violation
        title:
          type: string
          description: 'A short, summary of the problem type. Written in english and readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable.

            '
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          example: 503
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Connection to database timed out
        instance:
          type: string
          minLength: 3
          maxLength: 8000
          format: uri
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
    authError_2:
      type: object
      description: error response on HTTP 400 from auth/token per https://www.rfc-editor.org/rfc/rfc6749
      required:
      - error
      properties:
        error:
          type: string
          description: "As described in rfc6749\ninvalid_request – The request is missing a parameter so the server can’t proceed with the request.\n  This may also be returned if the request includes an unsupported parameter or repeats a parameter.\ninvalid_client – Client authentication failed, such as if the request contains an invalid\n  client ID or secret. Send an HTTP 401 response in this case.\ninvalid_grant – The authorization code (or user’s password for the password grant type) is\n  invalid or expired. This is also the error you would return if the redirect URL given in\n  the authorization grant does not match the URL provided in this access token request.\ninvalid_scope – For access token requests that include a scope (password or client_credentials grants),\n  this error indicates an invalid scope value in the request.\nunauthorized_client – This client is not authorized to use the requested grant type. For example,\n  if you restrict which applications can use the Implicit grant, you would return this error for\n  the other apps.\nunsupported_grant_type – If a grant type is requested that the authorization server doesn’t recognize,\n  use this code. Note that unknown grant types also use this specific error code rather than using the\n  invalid_request above.\n"
          example: invalid_request
          enum:
          - invalid_request
          - invalid_client
          - invalid_grant
          - invalid_scope
          - unauthorized_client
          - unsupported_grant_type
        error_description:
          type: string
          description: Should be a sentence or two at most describing the circumstance of the error
          example: Request was missing the 'client_id' parameter.
        error_uri:
          type: string
          format: uri
          minLength: 2
          maxLength: 8000
          description: Optional reference to more detailed error description
          example: https://example.com/docs/oauth-errors
  responses:
    notImplemented:
      description: Not implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_2'
    internalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_2'
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_2'
    badRequest:
      description: The request is malformed or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_2'
    badRequestOAuth:
      description: OAuth 2.0 token error response (RFC 6749)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/authError_2'
    notImplemented_2:
      description: Not implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_3'
    internalServerError_2:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_3'
    unauthorized_2:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_3'
    badRequest_2:
      description: The request is malformed or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem_3'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: Client credential flow.
      flows:
        clientCredentials:
          tokenUrl: auth/token
          scopes:
            read_all: VENs and BL can read all resources
            write_programs: Only BL can write to programs
            write_events: Only BL can write to events
            write_reports: only VENs can write to reports
            write_subscriptions: VENs and BL can write to subscriptions
            write_vens: VENS and BL can write to vens and resources
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- openadr-3-0-0-openapi.yaml
- openadr-3-0-1-openapi.yaml
- openadr-3-1-0-openapi.yaml
- openadr-3-1-1-openapi.yaml