oauth.yaml

---
swagger: '2.0'
info:
  version: 1.0.0
  title: OAuth Service
securityDefinitions:
  basicAuth:
    type: basic
paths:
  /oauth/authorize:
    post:
      tags:
      - OAuth
      summary: Obtain an authorization grant
      description: |
        The authorization endpoint is used to obtain an authorization grant.
        The authorization endpoint is used by the authorization code grant
        type and implicit grant type flows.
      operationId: authorize
      produces:
      - application/json
      parameters:
      - in: query
        name: response_type
        type: string
        required: true
        description: |
          The value MUST be one of
          - "code" for requesting an
          authorization code as described by https://tools.ietf.org/html/rfc6749#section-4.1.1,
          - "token" for requesting an access token (implicit grant) as described
          by https://tools.ietf.org/html/rfc6749#section-4.2.1
        type: string
      - in: query
        name: client_id
        type: string
        required: true
        description: |
          The client identifier as described in https://tools.ietf.org/html/rfc6749#section-2.2
      - in: query
        name: redirect_uri
        type: string
        required: false
        description: |
          As described in https://tools.ietf.org/html/rfc6749#section-3.1.2
      - in: query
        name: scope
        type: string
        required: false
        description: |
          The value of the scope parameter is expressed as a list of space-
          delimited, case-sensitive strings.  The strings are defined by the
          authorization server.  If the value contains multiple space-delimited
          strings, their order does not matter, and each string adds an
          additional access range to the requested scope. See https://tools.ietf.org/html/rfc6749#section-3.3.
      - in: query
        name: state
        type: string
        required: false
        description: |
          RECOMMENDED.  An opaque value used by the client to maintain
          state between the request and callback.  The authorization
          server includes this value when redirecting the user-agent back
          to the client.  The parameter SHOULD be used for preventing
          cross-site request forgery as described in https://tools.ietf.org/html/rfc6749#section-10.12.
      responses:
        302:
          description: |
            If the resource owner grants the access request, the authorization
            server issues an authorization code and delivers it to the client by
            adding the following parameters to the query component of the
            redirection URI using the "application/x-www-form-urlencoded" format.
            See https://tools.ietf.org/html/rfc6749#section-4.1.2.
          headers:
            Location:
              type: "string"
        403:
          description: Error during authorization
        400:
          description: Malformed request
        500:
          description: Something went wrong
  /oauth/token:
    post:
      tags:
      - OAuth
      summary: Obtain an acess token.
      security:
      - basicAuth: []
      description: |
        The token endpoint is used by the client to obtain an access token by
        presenting its authorization grant or refresh token.  The token
        endpoint is used with every authorization grant except for the
        implicit grant type (since an access token is issued directly).
      operationId: token
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
        - application/x-www-form-urlencoded
      parameters:
      - in: body
        name: token_request
        schema:
          "$ref": "#/definitions/TokenRequest"
      responses:
        200:
          description: Access token
          schema:
            "$ref": "#/definitions/Token"
        403:
          description: Access denied
definitions:
  TokenRequest:
    properties:
      grant_type:
        type: string
      code:
        type: string
      client_id:
        type: string
      client_secret:
        type: string
      redirect_uri:
        type: string
      scope: # see issue #48
        type: string
  Token:
    properties:
      access_token:
        type: string
      token_type:
        type: string
      state:
        type: string