Last active
April 20, 2019 20:30
-
-
Save MikeRalphson/72e8172bddfa4de7330c9e218b95401f to your computer and use it in GitHub Desktop.
Example of converted Swagger 2.0 API definition
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| openapi: 3.0.0-RC1 | |
| servers: | |
| - url: 'https://connect.authentiq.io/' | |
| info: | |
| title: Authentiq Connect API | |
| version: '1.0' | |
| description: > | |
| Authentiq Connect OAuth 2.0 and OpenID Connect API reference. | |
| Learn about [Authentiq ID](https://www.authentiq.com/) or check out the | |
| [Authentiq Connect](https://developers.authentiq.com) developer | |
| documentation. | |
| termsOfService: 'https://www.authentiq.com/tos/' | |
| contact: | |
| name: Team Authentiq | |
| url: 'https://www.authentiq.com/' | |
| email: hello@authentiq.com | |
| paths: | |
| /authorize: | |
| get: | |
| summary: Authenticate a user | |
| description: > | |
| Start a session with Authentiq Connect and authenticate a user. | |
| Example: | |
| ``` | |
| GET | |
| https://connect.authentiq.io/authorize?client_id=<your-client-id>&response_type=code+id_token&scope=openid+email&redirect_uri=<your-redirect-uri>&state=0123456789 | |
| ``` | |
| This endpoint is compatible with OpenID Connect and also supports the | |
| POST method, in which case the parameters are passed as a form post. | |
| See also: | |
| - [OAuth 2.0 Authorization Endpoint](http://tools.ietf.org/html/rfc6749#section-3.1) | |
| - [OIDC Authentication request](http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) | |
| - [OIDC Successful Authentication response](http://openid.net/specs/openid-connect-core-1_0.html#AuthResponse) | |
| - [OIDC Error Authentication response](http://openid.net/specs/openid-connect-core-1_0.html#AuthError) | |
| tags: | |
| - Authentication | |
| operationId: authorize | |
| parameters: | |
| - name: client_id | |
| in: query | |
| description: > | |
| A client ID obtained from the | |
| [Dashboard](https://dashboard.authentiq.com/). | |
| required: true | |
| schema: | |
| type: string | |
| - name: response_type | |
| in: query | |
| description: > | |
| The OIDC response type to use for this authentication flow. Valid | |
| choices are `code`, `id_token`, `token`, `token id_token`, `code | |
| id_token` `code token` and `code token id_token`, but a client can | |
| be configured with a more restricted set. | |
| required: true | |
| schema: | |
| type: string | |
| - name: scope | |
| in: query | |
| description: > | |
| The space-separated identity claims to request from the end-user. | |
| Always include `openid` as a scope for compatibility with OIDC. | |
| required: true | |
| schema: | |
| type: string | |
| - name: redirect_uri | |
| in: query | |
| description: > | |
| The location to redirect to after (un)successful authentication. See | |
| OIDC for the parameters passed in the query string | |
| (`response_mode=query`) or as fragments (`response_mode=fragment`). | |
| Unless the client is in test-mode this must be one of the registered | |
| redirect URLs. | |
| required: true | |
| schema: | |
| type: string | |
| - name: state | |
| in: query | |
| description: > | |
| An opaque string that will be passed back to the redirect URL and | |
| therefore can be used to communicate client side state and prevent | |
| CSRF attacks. | |
| required: true | |
| schema: | |
| type: string | |
| - name: response_mode | |
| in: query | |
| description: > | |
| Whether to append parameters to the redirect URL in the query string | |
| (`query`) or as fragments (`fragment`). This option usually has a | |
| sensible default for each of the response types. | |
| required: false | |
| schema: | |
| type: string | |
| - name: nonce | |
| in: query | |
| description: > | |
| An nonce provided by the client (and opaque to Authentiq Connect) | |
| that will be included in any ID Token generated for this session. | |
| Clients should use the nonce to mitigate replay attacks. | |
| required: false | |
| schema: | |
| type: string | |
| - name: display | |
| in: query | |
| description: > | |
| The authentication display mode, which can be one of `page`, `popup` | |
| or `modal`. Defaults to `page`. | |
| required: false | |
| schema: | |
| type: string | |
| default: page | |
| - name: prompt | |
| in: query | |
| description: > | |
| Space-delimited, case sensitive list of ASCII string values that | |
| specifies whether the Authorization Server prompts the End-User for | |
| reauthentication and consent. The supported values are: `none`, | |
| `login`, `consent`. If `consent` the end-user is asked to | |
| (re)confirm what claims they share. Use `none` to check for an | |
| active session. | |
| required: false | |
| schema: | |
| type: string | |
| default: login | |
| - name: max_age | |
| in: query | |
| description: > | |
| Specifies the allowable elapsed time in seconds since the last time | |
| the end-user was actively authenticated. | |
| required: false | |
| schema: | |
| type: integer | |
| default: 0 | |
| - name: ui_locales | |
| in: query | |
| description: > | |
| Specifies the preferred language to use on the authorization page, | |
| as a space-separated list of BCP47 language tags. Ignored at the | |
| moment. | |
| required: false | |
| schema: | |
| type: string | |
| responses: | |
| '302': | |
| description: | | |
| A successful or erroneous authentication response. | |
| '303': | |
| description: | | |
| *Sign in with Authentiq* page, popup or modal. | |
| externalDocs: | |
| description: OpenID Authorization Endpoint | |
| url: >- | |
| http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint | |
| /token: | |
| post: | |
| summary: Obtain an ID Token | |
| description: > | |
| Exchange en authorization code for an ID Token or Access Token. | |
| This endpoint supports both `client_secret_post` and | |
| `client_secret_basic` authenticatino methods, as specified by the | |
| client's `token_endpoint_auth_method`. | |
| See also: | |
| - [OIDC Token Endpoint](http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest) | |
| - [OIDC Successful Token response](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse) | |
| - [OIDC Token Error response](http://openid.net/specs/openid-connect-core-1_0.html#TokenError) | |
| tags: | |
| - Authentication | |
| operationId: token | |
| parameters: | |
| - name: Authorization | |
| in: header | |
| description: | | |
| HTTP Basic authorization header. | |
| required: false | |
| schema: | |
| type: string | |
| responses: | |
| '200': | |
| $ref: '#/components/responses/Token' | |
| '400': | |
| $ref: '#/components/responses/OAuth2Error' | |
| '401': | |
| $ref: '#/components/responses/OAuth2Error' | |
| externalDocs: | |
| description: OpenID Token Endpoint | |
| url: 'http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint' | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| client_id: | |
| description: | | |
| The registered client ID. | |
| type: string | |
| client_secret: | |
| description: | | |
| The registered client ID secret. | |
| type: string | |
| format: password | |
| grant_type: | |
| description: | | |
| The authorization grant type, must be `authorization_code`. | |
| type: string | |
| code: | |
| description: > | |
| The authorization code previously obtained from the | |
| Authentication endpoint. | |
| type: string | |
| redirect_uri: | |
| description: > | |
| The redirect URL that was used previously with the | |
| Authentication endpoint. | |
| type: string | |
| required: | |
| - client_id | |
| /userinfo: | |
| get: | |
| summary: Retrieve their user profile | |
| tags: | |
| - Authentication | |
| description: > | |
| Use this endpoint to retrieve a user's profile in case you've not | |
| already obtained enough details from the ID Token via the Token | |
| Endpoint. | |
| See also: | |
| - [OIDC UserInfo endpoint](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo) | |
| operationId: userInfo | |
| responses: | |
| '200': | |
| $ref: '#/components/responses/UserInfo' | |
| '401': | |
| $ref: '#/components/responses/OAuth2Error' | |
| default: | |
| $ref: '#/components/responses/OAuth2Error' | |
| security: | |
| - oauth_code: | |
| - oidc | |
| - phone | |
| - address | |
| - 'aq:location' | |
| - 'aq:name' | |
| - 'aq:push' | |
| - oauth_implicit: | |
| - oidc | |
| - phone | |
| - address | |
| - 'aq:location' | |
| - 'aq:name' | |
| - 'aq:push' | |
| /client: | |
| get: | |
| summary: List clients | |
| tags: | |
| - Client Management | |
| description: | | |
| Retrieve a list of clients. | |
| operationId: client | |
| responses: | |
| '200': | |
| description: A list of Client Objects. | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/Client' | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/Client' | |
| application/problem+json: | |
| schema: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/Client' | |
| text/html: | |
| schema: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/Client' | |
| default: | |
| $ref: '#/components/responses/OAuth2Error' | |
| security: | |
| - client_registration_token: [] | |
| - oauth_code: [] | |
| - oauth_implicit: [] | |
| post: | |
| summary: Register a client | |
| tags: | |
| - Client Management | |
| description: > | |
| Register a new client with this Authentiq Connect provider. | |
| This endpoint is compatible with [OIDC's Client | |
| Registration](http://openid.net/specs/openid-connect-registration-1_0.html) | |
| extension. | |
| See also: | |
| - [OIDC Client Registration | |
| Endpoint](http://openid.net/specs/openid-connect-registration-1_0.html#ClientRegistration) | |
| operationId: createClient | |
| parameters: [] | |
| responses: | |
| '201': | |
| description: Client created | |
| headers: | |
| Location: | |
| description: URL of new client resource | |
| schema: | |
| type: string | |
| default: | |
| $ref: '#/components/responses/ProblemDetail' | |
| security: | |
| - client_registration_token: [] | |
| - oauth_code: [] | |
| - oauth_implicit: [] | |
| requestBody: | |
| $ref: '#/components/requestBodies/Client' | |
| '/client/{client_id}': | |
| get: | |
| summary: View a client | |
| tags: | |
| - Client Management | |
| description: > | |
| Retrieve the configuration of a previously registered client. | |
| See also: | |
| - [OIDC Client Configuration | |
| Endpoint](http://openid.net/specs/openid-connect-registration-1_0.html#ClientConfigurationEndpoint) | |
| operationId: getClient | |
| parameters: | |
| - $ref: '#/components/parameters/client_id' | |
| responses: | |
| '200': | |
| description: Client found | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| application/x-www-form-urlencoded: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| application/problem+json: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| text/html: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| default: | |
| $ref: '#/components/responses/OAuth2Error' | |
| security: | |
| - client_registration_token: [] | |
| - oauth_code: [] | |
| - oauth_implicit: [] | |
| put: | |
| summary: Update a client | |
| tags: | |
| - Client Management | |
| description: > | |
| Update the configuration of a previously registered client. | |
| See also: | |
| - [OIDC Client Configuration | |
| Endpoint](http://openid.net/specs/openid-connect-registration-1_0.html#ClientConfigurationEndpoint) | |
| operationId: updateClient | |
| parameters: | |
| - $ref: '#/components/parameters/client_id' | |
| responses: | |
| '200': | |
| description: Client updated | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| application/x-www-form-urlencoded: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| application/problem+json: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| text/html: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| default: | |
| $ref: '#/components/responses/ProblemDetail' | |
| security: | |
| - client_registration_token: [] | |
| - oauth_code: [] | |
| - oauth_implicit: [] | |
| requestBody: | |
| $ref: '#/components/requestBodies/Client' | |
| delete: | |
| summary: Delete a client | |
| tags: | |
| - Client Management | |
| description: | | |
| Delete a previously registered client. | |
| operationId: clientClient_id | |
| parameters: | |
| - $ref: '#/components/parameters/client_id' | |
| responses: | |
| '204': | |
| description: Client deleted | |
| default: | |
| $ref: '#/components/responses/ProblemDetail' | |
| security: | |
| - client_registration_token: [] | |
| - oauth_code: [] | |
| - oauth_implicit: [] | |
| '/{client_id}/iframe': | |
| get: | |
| tags: | |
| - Session Management | |
| summary: Include a session iframe | |
| description: > | |
| An OpenID Connect Session Management iframe to facilitate e.g. single | |
| sign-on or remote logouts. | |
| The iframe implements the OIDC postMessage-based [change notification | |
| protocol](http://openid.net/specs/openid-connect-session-1_0.html#ChangeNotification) | |
| via which a client can receive notifications about session state | |
| changes. | |
| See also: | |
| - [OIDC OP | |
| iframe](http://openid.net/specs/openid-connect-session-1_0.html#OPiframe) | |
| operationId: authorizeIframe | |
| parameters: | |
| - $ref: '#/components/parameters/client_id' | |
| responses: | |
| '200': | |
| description: OK | |
| headers: | |
| Cache-Control: | |
| description: 'public, max-age=7200' | |
| schema: | |
| type: string | |
| externalDocs: | |
| description: Authentiq Developer Docs | |
| url: 'https://developers.authentiq.com/' | |
| components: | |
| schemas: | |
| Token: | |
| description: | | |
| Successful token response | |
| required: | |
| - token_type | |
| properties: | |
| token_type: | |
| type: string | |
| access_token: | |
| description: The access token issued by the authorization server. | |
| type: string | |
| id_token: | |
| description: ID Token value associated with the authenticated session. | |
| type: string | |
| refresh_token: | |
| description: 'The refresh token issued to the client, if any.' | |
| type: string | |
| expires_in: | |
| description: The lifetime in seconds of the access token. | |
| type: integer | |
| format: int32 | |
| expires_at: | |
| description: The time the access token will expire in seconds since epoch. | |
| type: integer | |
| format: int64 | |
| scope: | |
| description: The scope of the granted tokens. | |
| type: string | |
| OAuth2Error: | |
| description: | | |
| Error Response defined as in Section 5.2 of OAuth 2.0 [RFC6749]. | |
| required: | |
| - error | |
| properties: | |
| error: | |
| type: string | |
| error_description: | |
| type: string | |
| ProblemDetail: | |
| description: | | |
| HTTP Problem Detail | |
| required: | |
| - type | |
| - status | |
| properties: | |
| type: | |
| type: string | |
| default: 'about:blank' | |
| title: | |
| type: string | |
| description: | | |
| Human-readable summary of the problem type. | |
| status: | |
| type: integer | |
| description: | | |
| The HTTP status code for this occurrence of the problem. | |
| detail: | |
| type: string | |
| description: > | |
| Human-readable explanation specific to this occurrence of the | |
| problem. | |
| Session: | |
| description: Session object | |
| properties: | |
| version: | |
| type: integer | |
| sub: | |
| type: string | |
| session_id: | |
| type: string | |
| session_state: | |
| type: string | |
| session_uri: | |
| type: string | |
| client_id: | |
| type: string | |
| scopes: | |
| type: array | |
| items: | |
| type: string | |
| scopes_optional: | |
| type: array | |
| items: | |
| type: string | |
| scopes_required: | |
| type: array | |
| items: | |
| type: string | |
| scopes_signed: | |
| type: array | |
| items: | |
| type: string | |
| tokens_seen: | |
| type: array | |
| items: | |
| type: string | |
| scopes_seen: | |
| type: array | |
| items: | |
| type: string | |
| redirect_uri: | |
| type: string | |
| response_type: | |
| type: string | |
| response_mode: | |
| type: string | |
| nonce: | |
| type: string | |
| created_at: | |
| type: string | |
| connected_at: | |
| type: string | |
| format: date-time | |
| authenticated_at: | |
| type: string | |
| format: date-time | |
| concluded_at: | |
| type: string | |
| format: date-time | |
| deleted_at: | |
| type: string | |
| format: date-time | |
| client_name: | |
| type: string | |
| client_uri: | |
| type: string | |
| logo_uri: | |
| type: string | |
| policy_uri: | |
| type: string | |
| tos_uri: | |
| type: string | |
| contacts: | |
| type: array | |
| items: | |
| type: string | |
| UserInfo: | |
| description: OIDC UserInfo structure | |
| required: | |
| - sub | |
| properties: | |
| sub: | |
| type: string | |
| name: | |
| type: string | |
| given_name: | |
| type: string | |
| family_name: | |
| type: string | |
| email: | |
| type: string | |
| email_verified: | |
| type: boolean | |
| phone_number: | |
| type: string | |
| phone_number_verified: | |
| type: boolean | |
| address: | |
| $ref: '#/components/schemas/Address' | |
| 'aq:location': | |
| description: Geolocation structure | |
| properties: | |
| latitude: | |
| type: number | |
| format: float | |
| longitude: | |
| type: number | |
| format: float | |
| address: | |
| $ref: '#/components/schemas/Address' | |
| Address: | |
| description: OIDC Address structure | |
| properties: | |
| street_address: | |
| type: string | |
| locality: | |
| type: string | |
| region: | |
| type: string | |
| postal_code: | |
| type: string | |
| country: | |
| type: string | |
| Client: | |
| description: Client object | |
| required: | |
| - client_name | |
| - client_uri | |
| properties: | |
| client_id: | |
| type: string | |
| redirect_uris: | |
| type: array | |
| items: | |
| type: string | |
| response_types: | |
| type: array | |
| items: | |
| type: string | |
| grant_types: | |
| type: array | |
| items: | |
| type: string | |
| application_type: | |
| type: string | |
| contacts: | |
| type: array | |
| items: | |
| type: string | |
| client_name: | |
| type: string | |
| logo_uri: | |
| type: string | |
| client_uri: | |
| type: string | |
| policy_uri: | |
| type: string | |
| tos_uri: | |
| type: string | |
| default_max_age: | |
| type: integer | |
| format: int64 | |
| default_scopes: | |
| type: array | |
| items: | |
| type: string | |
| responses: | |
| Token: | |
| description: Token response | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| $ref: '#/components/schemas/Token' | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/Token' | |
| application/problem+json: | |
| schema: | |
| $ref: '#/components/schemas/Token' | |
| text/html: | |
| schema: | |
| $ref: '#/components/schemas/Token' | |
| UserInfo: | |
| description: UserInfo response | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| $ref: '#/components/schemas/UserInfo' | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/UserInfo' | |
| application/problem+json: | |
| schema: | |
| $ref: '#/components/schemas/UserInfo' | |
| text/html: | |
| schema: | |
| $ref: '#/components/schemas/UserInfo' | |
| OAuth2Error: | |
| description: OAuth 2.0 error response | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| $ref: '#/components/schemas/OAuth2Error' | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/OAuth2Error' | |
| application/problem+json: | |
| schema: | |
| $ref: '#/components/schemas/OAuth2Error' | |
| text/html: | |
| schema: | |
| $ref: '#/components/schemas/OAuth2Error' | |
| ProblemDetail: | |
| description: Problem Detail error response | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| $ref: '#/components/schemas/ProblemDetail' | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/ProblemDetail' | |
| application/problem+json: | |
| schema: | |
| $ref: '#/components/schemas/ProblemDetail' | |
| text/html: | |
| schema: | |
| $ref: '#/components/schemas/ProblemDetail' | |
| parameters: | |
| client_id: | |
| name: client_id | |
| in: path | |
| description: Client identifier | |
| required: true | |
| schema: | |
| type: string | |
| examples: {} | |
| requestBodies: | |
| Client: | |
| content: | |
| application/json: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| multipart/form-data: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| application/x-www-form-urlencoded: | |
| schema: | |
| $ref: '#/components/schemas/Client' | |
| description: Client Object | |
| securitySchemes: | |
| client_secret: | |
| description: Session management by confidential clients. | |
| type: oauth2 | |
| flows: | |
| password: | |
| tokenUrl: 'https://connect.authentiq.io/token' | |
| scopes: | |
| clients: Enable client management | |
| client_registration_token: | |
| description: Client management via registration token. | |
| type: apiKey | |
| name: Authorization | |
| in: header | |
| user_jwt: | |
| description: Session management by Authentiq ID. | |
| type: oauth2 | |
| flows: | |
| clientCredentials: | |
| tokenUrl: 'https://connect.authentiq.io/token' | |
| scopes: | |
| session: Enable session management | |
| oauth_code: | |
| description: End-user authentication. | |
| type: oauth2 | |
| flows: | |
| authorizationCode: | |
| authorizationUrl: 'https://connect.authentiq.io/authorize' | |
| tokenUrl: 'https://connect.authentiq.io/token' | |
| scopes: | |
| oidc: Enable OIDC flow | |
| email: The user's email address | |
| phone: The user's phone number | |
| address: The user's postal address | |
| 'aq:location': The user's current location | |
| 'aq:name': The user's full name | |
| 'aq:push': Enable *One click sign-in* | |
| oauth_implicit: | |
| description: End-user authentication. | |
| type: oauth2 | |
| flows: | |
| implicit: | |
| authorizationUrl: 'https://connect.authentiq.io/authorize' | |
| scopes: | |
| oidc: Enable OIDC flow | |
| email: The user's email address | |
| phone: The user's phone number | |
| address: The user's postal address | |
| 'aq:location': The user's current location | |
| 'aq:name': The user's full name | |
| 'aq:push': Enable *One click sign-in* | |
| headers: {} |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment