Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Example of converted Swagger 2.0 API definition
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
- email
- phone
- address
- 'aq:location'
- 'aq:name'
- 'aq:push'
- oauth_implicit:
- oidc
- email
- 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