Skip to content

Instantly share code, notes, and snippets.

@MikeRalphson
Created May 23, 2017 05:52
Show Gist options
  • Save MikeRalphson/0c42c2778ea7a7a6fc0b5d59b4d7868e to your computer and use it in GitHub Desktop.
Save MikeRalphson/0c42c2778ea7a7a6fc0b5d59b4d7868e to your computer and use it in GitHub Desktop.
Authentiq.Io Swagger 2.0 API definition
swagger: '2.0'
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
host: connect.authentiq.io
basePath: /
schemes:
- https
consumes:
- application/x-www-form-urlencoded
- application/json
produces:
- application/x-www-form-urlencoded
- application/json
- application/problem+json
- text/html
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
type: string
description: >
A client ID obtained from the
[Dashboard](https://dashboard.authentiq.com/).
required: true
- name: response_type
in: query
type: string
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
- name: scope
in: query
type: string
description: >
The space-separated identity claims to request from the end-user.
Always include `openid` as a scope for compatibility with OIDC.
required: true
- name: redirect_uri
in: query
type: string
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
- name: state
in: query
type: string
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
- name: response_mode
in: query
type: string
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
- name: nonce
in: query
type: string
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
- name: display
in: query
type: string
description: >
The authentication display mode, which can be one of `page`, `popup`
or `modal`. Defaults to `page`.
required: false
default: page
- name: prompt
in: query
type: string
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
default: login
- name: max_age
in: query
type: integer
description: >
Specifies the allowable elapsed time in seconds since the last time
the end-user was actively authenticated.
required: false
default: 0
- name: ui_locales
in: query
type: string
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
produces:
- text/html
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
consumes:
- application/x-www-form-urlencoded
parameters:
- name: Authorization
in: header
description: |
HTTP Basic authorization header.
required: false
type: string
- name: client_id
in: formData
description: |
The registered client ID.
required: true
type: string
- name: client_secret
in: formData
description: |
The registered client ID secret.
required: true
type: string
format: password
- name: grant_type
in: formData
description: |
The authorization grant type, must be `authorization_code`.
required: true
type: string
- name: code
in: formData
description: >
The authorization code previously obtained from the Authentication
endpoint.
required: true
type: string
- name: redirect_uri
in: formData
description: >
The redirect URL that was used previously with the Authentication
endpoint.
required: true
type: string
produces:
- application/json
responses:
'200':
$ref: '#/responses/Token'
'400':
$ref: '#/responses/OAuth2Error'
'401':
$ref: '#/responses/OAuth2Error'
externalDocs:
description: OpenID Token Endpoint
url: 'http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint'
/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
produces:
- application/json
responses:
'200':
$ref: '#/responses/UserInfo'
'401':
$ref: '#/responses/OAuth2Error'
default:
$ref: '#/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
produces:
- application/json
responses:
'200':
description: A list of Client Objects.
schema:
type: array
items:
$ref: '#/definitions/Client'
default:
$ref: '#/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
consumes:
- application/json
- multipart/form-data
parameters:
- $ref: '#/parameters/Client'
responses:
'201':
description: Client created
headers:
Location:
description: URL of new client resource
type: string
default:
$ref: '#/responses/ProblemDetail'
security:
- client_registration_token: []
- oauth_code: []
- oauth_implicit: []
'/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
produces:
- application/json
parameters:
- $ref: '#/parameters/client_id'
responses:
'200':
description: Client found
schema:
$ref: '#/definitions/Client'
default:
$ref: '#/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
consumes:
- application/json
- multipart/form-data
produces:
- application/json
parameters:
- $ref: '#/parameters/client_id'
- $ref: '#/parameters/Client'
responses:
'200':
description: Client updated
schema:
$ref: '#/definitions/Client'
default:
$ref: '#/responses/ProblemDetail'
security:
- client_registration_token: []
- oauth_code: []
- oauth_implicit: []
delete:
summary: Delete a client
tags:
- Client Management
description: |
Delete a previously registered client.
operationId: clientClient_id
parameters:
- $ref: '#/parameters/client_id'
responses:
'204':
description: Client deleted
default:
$ref: '#/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: '#/parameters/client_id'
produces:
- test/html
responses:
'200':
description: OK
headers:
Cache-Control:
description: 'public, max-age=7200'
type: string
definitions:
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: '#/definitions/Address'
'aq:location':
description: Geolocation structure
properties:
latitude:
type: number
format: float
longitude:
type: number
format: float
address:
$ref: '#/definitions/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
parameters:
Client:
name: body
in: body
description: Client Object
required: true
schema:
$ref: '#/definitions/Client'
client_id:
name: client_id
in: path
description: Client identifier
required: true
type: string
responses:
Token:
description: Token response
schema:
$ref: '#/definitions/Token'
UserInfo:
description: UserInfo response
schema:
$ref: '#/definitions/UserInfo'
OAuth2Error:
description: OAuth 2.0 error response
schema:
$ref: '#/definitions/OAuth2Error'
ProblemDetail:
description: Problem Detail error response
schema:
$ref: '#/definitions/ProblemDetail'
securityDefinitions:
client_secret:
description: Session management by confidential clients.
type: oauth2
flow: 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
flow: application
tokenUrl: 'https://connect.authentiq.io/token'
scopes:
session: Enable session management
oauth_code:
description: End-user authentication.
type: oauth2
flow: accessCode
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
flow: 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*
externalDocs:
description: Authentiq Developer Docs
url: 'https://developers.authentiq.com/'
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment