mod-authtoken/src/main/resources/openapi/token-1.0.yaml at master · folio-org/mod-authtoken · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
openapi: 3.0.0
info:
  title: mod-authtoken API
  version: v1
paths:
  # NOTE This module relies on its folio-vertx-lib dependency to handle the /_/tenant
  # route. Please see its yaml specification for /_/tenant here:
  # https://dev.folio.org/reference/api/#folio-vertx-lib
  /token:
    parameters:
      # folio-vertx-lib has header files but they don't make the headers required so we override
      # that behavior here since these two headers are required.
      - $ref: headers/okapi-tenant-required.yaml
      - $ref: headers/okapi-url-required.yaml
    post:
      description: Deprecated. Will be removed in a future release. Please use /token/sign instead. Returns a signed, non-expiring legacy access token.
      operationId: token-legacy
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/signTokenPayload"
        required: true
      responses:
        "201":
          description: Created and signed token successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tokenResponseLegacy"
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /refreshtoken:
    parameters:
      - $ref: headers/okapi-tenant-required.yaml
      - $ref: headers/okapi-url-required.yaml
    post:
      description: |
        Returns a signed, expiring refresh token. This is a legacy endpoint and should not be
        called by new code and will soon be fully depreciated.
      operationId: token-sign-legacy
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/signRefreshToken"
        required: true
      responses:
        "201":
          description: Created and signed token successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/token"
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /token/sign:
    parameters:
      # folio-vertx-lib has header files but they don't make the headers required so we override
      # that behavior here since these two headers are required.
      - $ref: headers/okapi-tenant-required.yaml
      - $ref: headers/okapi-url-required.yaml
    post:
      description: |
        Returns a signed, expiring access token and refresh token. Also returns the expiration
        of each token in the body of the response. The access token time to live is 10 minutes and
        the refresh token is one week.
      operationId: token-sign
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/signTokenPayload"
        required: true
      responses:
        "201":
          description: Created and signed tokens successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tokenResponse"
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /token/refresh:
    parameters:
      - $ref: headers/okapi-tenant-required.yaml
      - $ref: headers/okapi-url-required.yaml
    post:
      description: |
        Returns a new refresh token and a new access token. Also returns the expiration of each token
        in the body of the response. Time to live is 10 minutes for the access token and one week for
        the refresh token.
      operationId: token-refresh
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/refreshToken"
        required: true
      responses:
        "201":
          description: Refreshed tokens successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tokenResponse"
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /token/invalidate:
    parameters:
      - $ref: headers/okapi-tenant-required.yaml
      - $ref: headers/okapi-url-required.yaml
    post:
      description: Invalidate a single refresh token. An access token cannot be invalidated and remains valid until its expiration time; this is by design because the access token is stateless.
      operationId: token-invalidate
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/refreshToken"
        required: true
      responses:
        "204":
          description: Invalidated token successfully
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /token/invalidate-all:
    parameters:
      - $ref: headers/okapi-tenant-required.yaml
      - $ref: headers/okapi-url-required.yaml
    post:
      description: Invalidate all refresh tokens for a user. An access token cannot be invalidated and remains valid until its expiration time; this is by design because the access token is stateless.
      operationId: token-invalidate-all
      responses:
        "204":
          description: Invalidated tokens successfully
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
components:
  responses:
    trait_400:
      description: Bad request
      content:
        text/plain:
          schema:
            type: string
            example: Invalid JSON in request
        application/json:
          schema:
            type: object
            example: { "error": "Invalid JSON in request" }
    trait_500:
      description: Internal error
      content:
        text/plain:
          schema:
            type: string
            example: Internal server error, contact administrator
  schemas:
    refreshToken:
      $ref: schemas/refreshToken.json
    tokenResponse:
      $ref: schemas/tokenResponse.json
    tokenResponseLegacy:
      $ref: schemas/tokenResponseLegacy.json
    signTokenPayload:
      $ref: schemas/signTokenPayload.json
    signRefreshToken:
      $ref: schemas/signRefreshToken.json
    token:
      $ref: schemas/token.json