TOMP-API/TOMP-API-7-TECH.yaml at master · edwinvandenbelt/TOMP-API · 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
openapi: 3.1.0
info:
  title: Transport Operator MaaS Provider API
  description: "<h2>Context</h2>
    <p>This API allows technical communication between Transport Operators (TO) and MaaS providers (MP, and other resellers), to fulfill a complete MaaS user journey<br>
    For more information: <a href='https://github.com/TOMP-WG/TOMP-API/wiki/OpenAPI-entry-page'>TOMP-API wiki</a>, and <a href='https://github.com/TOMP-WG/TOMP-API/wiki/OpenAPI-code-convention'>Coding conventions</a>"
  version: "2.0.0"
  contact:
    name: TOMP working group
    url: https://github.com/TOMP-WG/TOMP-API
  license:
    name: Apache 2.0
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
  x-modules:
    - tech

tags:
  - name: tech
    description: technical functions of the API, also used in dataspaces

paths:
  /health:
    get:
      operationId: ping
      tags:
        - tech
      summary: "is the API up and running?"
      description: "This is a healthcheck ENDPOINT"
      responses:
        "204":
          description: successful operation
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /oauth/token:
    post:
      summary: "Token Endpoint"
      operationId: getToken
      tags:
      - tech
      security:
        - BasicAuth: [] # username/password
        - BearerAuth: [] # fixed JWT token
        - OAuth: [] # OAuth2 client credential flow
        - OAuthPKI: [] # mTLS
      description: This endpoint is used to obtain an access token and optionally an ID token
        through different OAuth 2.0 grant types, including Client Credentials Flow.
        Whenever the mTLS flow is taken, the properties will be ignored, and the access token
        will be generated based on the credentials in the certificate (O or CN).
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: [client_credentials, password, refresh_token]
                  description: "The grant type: 'client_credentials', 'password', or 'refresh_token'."
                  default: client_credentials
                username:
                  type: string
                  description: "The username"
                password:
                  type: string
                  description: "The password"
                client_id:
                  type: string
                  description: "The client ID (Client Credentials Flow)"
                client_secret:
                  type: string
                  description: "The client secret (Client Credentials Flow)"
      responses:
        '200':
          description: "Successful token issuance."
          content:
            application/json:
              schema:
                type: object
                required:
                - access_token
                properties:
                  access_token:
                    type: string
                    description: "The issued access token."
                  token_type:
                    type: string
                    description: "The type of the token."
                    default: "Bearer"
                  expires_in:
                    type: integer
                    description: "The lifetime of the access token in seconds."
        '400':
          description: "Bad Request: Invalid request or wrong grant type."
        '401':
          description: "Unauthorized: Invalid client ID or secret."
        '500':
          description: "Internal Server Error: Something went wrong."